Simulation

GLMOutputs

Return GLM output files.

Initialised at the completion of a GLM simulation to record the paths of output files. Provides methods to return the data in these files.

Attributes:

Name	Type	Description
sim_name	str	Name of the simulation.

__init__(sim_dir_path, out_dir='output', out_fn='output', sim_name='simulation')

Parameters:

Name	Type	Description	Default
sim_dir_path	str	Path to the simulation directory.	required
out_dir	str	Directory name containing the GLM output files. Set this to equal the out_dir parameter in the output block of the glm NML.	'output'
out_fn	str	Filename of the main NetCDF output file. Set this to equal the out_dir parameter in the output block of the glm NML.	'output'
sim_name	str	Name of the simulation.	'simulation'

get_csv_basenames()

Returns a list of CSV basenames in the outputs directory.

get_csv_path(csv_basename)

Returns the full file path of a CSV in the outputs directory.

Parameters:

Name	Type	Description	Default
csv_basename	str	The basename of a CSV in the outputs directory. To see possible basenames, use get_csv_basenames().	required

get_csv_pd(csv_basename)

Returns a Pandas DataFrame of a CSV in the outputs directory.

Parameters:

Name	Type	Description	Default
csv_basename	str	The basename of a CSV in the outputs directory. To see possible basenames, use get_csv_basenames().	required

get_netcdf()

Returns a netCDF4.Dataset instance of the netCDF output file.

get_netcdf_path()

Returns the path of the netCDF output file.

zip_csv_outputs()

Creates a zipfile of csv GLM outputs (csv outputs only).

Use this if you do not need a netCDF file of GLM outputs.

GLMSim

sim_name property writable

Simulation name.

Updating sim_name will also update the sim_name parameter of the glm_setup block.

__init__(sim_name, glm_nml=GLMNML(), aed_nml=AEDNML(), bcs={}, aed_dbase={}, sim_dir_path='.')

Parameters:

Name	Type	Description	Default
sim_name	str	The simulation name. Updates the sim_name parameter of the glm_setup block.	required
glm_nml	GLMNML	The GLMNML object of GLM model parameters.	GLMNML()
aed_nml	AEDNML	The aed_nml object of AED model parameters.	AEDNML()
bcs	Dict[str, DataFrame]	Dictionary of boundary condition dataframes. The keys are the basename (without extension) of the boundary condition file and the values are Pandas DataFrame objects. For example: {'met_data_filename': met_data_pd}.	{}
aed_dbase	Dict[str, DataFrame]	Dictionary of AED database dataframes. The keys are the basename (without extension) of the database file and the values are Pandas DataFrame objects. For example: {'aed_zoop_pars': aed_zoop_pars_pd}. Use read_aed_dbase() to read in database CSV files.	{}
sim_dir_path	str	Path to where the simulation directory should be created. Default is the current working directory.	'.'

from_example_sim(example_sim_name) classmethod

Initialise an instance of GLMSim from an example simulation.

Parameters:

Name	Type	Description	Default
example_sim_name	str	Name of an example simulation bundled with the glm-py package. See get_example_sim_names() for valid names.	required

from_file(glmpy_path) classmethod

Initialise an instance of GLMSim from a .glmpy file.

Parameters:

Name	Type	Description	Default
glmpy_path	str	Path to .glmpy file.	required

get_bc_pd(bcs_name)

Get a bcs dataframe.

Returns a Pandas DataFrame of a specified boundary condition.

Parameters:

Name	Type	Description	Default
bcs_name	str	Name of the boundary condition.	required

get_bcs_names()

List the bcs names.

Returns a list of the keys in the bcs dictionary,

get_block(nml_name, block_name)

Get a NML Block.

Returns an instance of a NMLBlock subclass from the NML.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required
block_name	str	The block name.	required

get_block_names(nml_name)

List the block names.

Returns a list of the name attribute for all NMLBlock subclass instances.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required

get_deepcopy()

Copy the GLMSim object.

Returns a deep copy of the GLMSim.

get_example_sim_names() staticmethod

Returns a list names for the example simulations bundled in the glm-py package.

get_nml(nml_name)

Get a NML.

Returns an instance of a NML subclass.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required

get_nml_names()

List the NML names.

Returns a list of the name attribute for all NML subclass instances.

get_param_names(nml_name, block_name)

List the parameter names in a block.

Returns a list of the name attribute for all NMLParam instances.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required
block_name	str	The block name.	required

get_param_units(nml_name, block_name, param_name)

Get a parameter's units.

Returns the units attribute of a NMLParam instance.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required
block_name	str	The block name.	required
param_name	str	The name of the parameter to return the value for.	required

get_param_value(nml_name, block_name, param_name)

Get a parameter value.

Returns the value attribute of a NMLParam instance.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required
block_name	str	The block name.	required
param_name	str	The name of the parameter to return the value for.	required

get_sim_dir()

Return the simulation directory.

iter_params()

Iterate over all NMLParam objects.

prepare_all_inputs()

Prepare all input files for GLM.

Creates the simulation directory and writes the NML, boundary condition, and database files. If the simulation directory already exists, the directory is first deleted.

prepare_bcs_and_dbase()

Prepare the boundary condition and database files.

Writes the boundary condition and datase files to the simulation directory. Creates the directory if it doesn't already exist.

prepare_nml()

Prepare the NML files.

Writes the NML files to the simulation directory. Creates the directory if it doesn't already exist.

rm_sim_dir()

Delete the simulation directory.

run(write_log=False, quiet=False, time_sim=False, glm_path=None)

Run the GLM simulation.

Validates simulation configuration, prepares input files, and then runs GLM.

Parameters:

Name	Type	Description	Default
write_log	bool	Write a log file as GLM runs.	False
quiet	bool	Suppress the GLM terminal output.	False
time_sim	bool	Prints "Starting {sim_name}" and "Finished {sim_name} in {total_duration}"	False
glm_path	Union[str, None]	Path to the GLM binary. If None, attempts to use the GLM binary included in glm-py's built distribution.	None

set_bc(bcs_name, bcs_pd)

Adds, or overrides, a boundary condition dataframe.

Parameters:

Name	Type	Description	Default
bcs_name	str	Boundary condition name.	required
bcs_pd	DataFrame	Pandas DataFrame of the boundary condition data.	required

set_block(nml_name, block_name, block)

Set a NML Block.

Overrides, or adds a new block, to a NML.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required
block_name	str	The block name.	required
block	NMLBlock	The block to set.	required

set_nml(nml_name, nml)

Set NML.

Overrides or adds a new NML.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required
nml	NML	The NML to set.	required

set_param_value(nml_name, block_name, param_name, value)

Set a parameter value.

Sets the value attribute of a NMLParam instance.

Parameters:

Name	Type	Description	Default
nml_name	str	The NML name.	required
block_name	str	The block name.	required
param_name	str	The parameter name.	required
value	Any	The parameter value to set.	required

to_file(glmpy_path)

Save the GLMSim object to a .glmpy file

Parameters:

Name	Type	Description	Default
glmpy_path	str	Output file path. Must have a .glmpy file extension.	required

validate()

Validate the simulation inputs.

MultiSim

Run GLMSim objects in parallel.

Uses Python's multiprocessing module to spawn separate processes for simultaneously running multiple GLMSim objects. Useful when many CPU cores are available and many permutations of a simulation need to be run. The number of concurrently running simulations is determined by the number of CPU cores set in the run() method.

Attributes:

Name	Type	Description
glm_sims	List[GLMSim]	A list of GLMSim objects to be run across multiple CPU cores.

__init__(glm_sims)

Parameters:

Name	Type	Description	Default
glm_sims	List[GLMSim]	A list of GLMSim objects to be run across multiple CPU cores.	required

cpu_count() staticmethod

Returns the number of CPU cores.

run(on_sim_end=None, cpu_count=None, write_log=True, time_sim=True, time_multi_sim=True, glm_path=None)

Run the multi-sim.

Parameters:

Name	Type	Description	Default
on_sim_end	Callable[[GLMSim, GLMOutputs], Any]	The function to run at the completion of GLMSim.run(). Must take a GLMSim and GLMOutputs object as arguments.	None
cpu_count	Union[int, None]	The number of CPU cores to use, i.e., the number of simulations to run in parallel. Default is the maximum number of cores available.	None
write_log	bool	Write a log file as GLM runs.	True
time_sim	bool	Prints "Starting {sim_name}" and "Finished {sim_name} in {total_duration}"	True
glm_path	Union[str, None]	Path to the GLM binary. If None, attempts to use the GLM binary included in glm-py's built distribution.	None

run_single_sim(glm_sim, on_sim_end, write_log=True, time_sim=True, glm_path=None)

Run a GLMSim on a single core.

Parameters:

Name	Type	Description	Default
glm_sim	GLMSim	The GLMSim to run.	required
on_sim_end	Callable[[GLMSim, GLMOutputs], Any]	The function to run at the completion of GLMSim.run(). Must take a GLMSim and GLMOutputs object as arguments.	required
write_log	bool	Write a log file as GLM runs.	True
time_sim	bool	Prints "Starting {sim_name}" and "Finished {sim_name} in {total_duration}"	True
glm_path	Union[str, None]	Path to the GLM binary. If None, attempts to use the GLM binary included in glm-py's built distribution.	None

glmpy_glm_path()

glm-py GLM binary path.

Returns the path to the GLM binary included with the glm-py built distribution. Returns None if the binary was not found.

read_aed_dbase(dbase_path)

Read an AED database CSV

Returns a Pandas DataFrame of the database that has been transposed to ensure consistent column data types.

Parameters:

Name	Type	Description	Default
dbase_path	str	Path to the AED database CSV	required

run_glm(sim_dir_path, sim_name='simulation', write_log=False, quiet=False, time_sim=False, glm_path=None)

Run GLM.

Runs the GLM binary by providing the path to the GLM NML file.

Parameters:

Name	Type	Description	Default
sim_dir_path	str	Path to the simulation directory that contains the glm3.nml file.	required
sim_name	str	Name of the simulation.	'simulation'
write_log	bool	Write a log file as GLM runs.	False
quiet	bool	Suppress the GLM terminal output.	False
time_sim	bool	Prints "Starting {sim_name}" and "Finished {sim_name} in {total_duration}"	False
glm_path	Union[str, None]	Path to the GLM binary. If None, attempts to use the GLM binary included in glm-py's built distribution.	None

write_aed_dbase(dbase_pd, dbase_path)

Write an AED database CSV.

Writes an AED database CSV that has been read by read_aed_dbase(). Transposes the data back to the original format.

Parameters:

Name	Type	Description	Default
dbase_pd	DataFrame	Pandas DataFrame of the database.	required
dbase_path	str	Path of the database CSV to write.	required