PECANS Core

class pecans.main.Domain(config: dict, output_dir: str | None = None)

Object that represents the model domain that the simulation occurs on

Parameters:

• config – a dictionary that contains the desired model setup as described in a PECANS config TOML file.

• output_dir – Directory to save the output files to. Only has an effect if write_output() is called without specifying a file name. Default is the current directory.

In a multibox model, the “domain” is the collection of boxes that collectively make up the area that the model is to simulate. In PECANS, that is represented by this object. Mainly, this stores information about the size and shape of the domain (i.e. how many boxes in each dimension, how large each box it, etc.) and the concentration of all the chemical species being tracked. It will also connect to the appropriate functions that calculate the change in concentrations due to chemistry, transport, and emissions.

The Domain object is initialized by calling it with a BetterConfig object from the utilities subpackage. Then to advance the model in time, call the step() method on the Domain instance, e.g.:

config = utils.config.load_config_file('pecans_config.cfg')
model_domain = Domain(config)
for t in range(100):
    model_domain.step()

By default, the domain will automatically write an output netCDF file based on the frequency in the configuration file. If you want to manually write the model state for any reason, you can call the write_output method.

execute(n_seconds_to_run=None)

Carry out the entire model run

Once the domain is configured, this will time step the model until the stop time is reached.

Parameters:

n_seconds_to_run (int or float) – optional, gives the number of seconds that the model should run for. If not given, then the run time option in the config is used (which is the most common approach; it is rare that a custom number of seconds to run would need to be specified.

Returns:

none

step()

Execute one model time step

This wil call, in sequence, the configured chemistry solver, transport solver, and emissions solver. It will automatically write an output file if the time elapsed since the last output file is longer than the output frequency specified in the configuration.

Returns:

none

write_output(output_file_name=None)

Write an output netCDF file representing the instantaneous current model state

Parameters:

output_file_name (str) –

optional, allows you to specify the desired output file name. If not given, it will default to

”pecans_output_DDDdHHhMMmSSs.nc”

where DDD, HH, MM, and SS are the days, minutes and seconds since the beginning of the model run. If an output name is not specified, the files will be saved in the directory that was specified by the output_dir argument to the constructor. If you specify the output file name in the call to this method, no directory is prepended; if you want to save to a directory other than the current one, you must specify that in your output file name.

Returns:

none