Simulation

GLMPostProcessor

Class to process outputs of GLM simulation.

Attributes:

Name	Type	Description
outputs_path	str	Path to directory where GLM outputs have been written.

Examples:

>>> import os
>>> import shutil

>>> from glmpy import simulation as sim

>>> files = {
>>>    "glm3.nml": os.path.join(os.getcwd(), "glm3.nml"),
>>>    "met.csv": os.path.join(os.getcwd(), "met.csv"),
>>> }

>>> # running local instance of GLM
>>> glm_run = sim.GLMSim(files, False, "/inputs")
>>> inputs_dir = glm_run.prepare_inputs()

>>> glm_run.glm_run(inputs_dir, "/glm/glm")

>>> outputs_dir = os.path.join(inputs_dir, "output")

>>> # initialise GLMPostProcessor object
>>> glm_process = sim.GLMPostProcessor(outputs_dir)

>>> # create zipfile of GLM outputs
>>> # csv file and netcdf
>>> # returns path to zipfile of outputs
>>> files_zip_path = glm_process.zip_outputs()

>>> # create zipfile of csv GLM outputs
>>> files_zip_csv_path = glm_process.zip_csvs()

>>> # create zipfile of JSON GLM outputs
>>> files_zip_json_path = glm_process.zip_json()

csv_to_json(csv_lake_fname, variables)

Converts outputs of GLM simulation in csv format to JSON.

Can be used as a step before saving GLM results to JSON files or to generate JSON formatted data that can be returned to clients for rendering in web browers; for example, if GLM is being used as part of a web application.

Parameters:

Name	Type	Description	Default
csv_lake_fname	str	File name of csv of outputs from GLM - lake.csv.	required
variables	list	List of variable names from lake.csv to select and convert to JSON format..	required

Returns:

Type	Description
dict JSON formatted results of GLM simulation.

csv_to_json_files()

Convert csv of GLM outputs to JSON format and writes to a .json file.

zip_csvs()

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

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

Returns:

Type	Description
str Path to zipfile of GLM outputs.

zip_json()

Creates a zipfile of csv GLM outputs converted to JSON format.

Use this, for example, if you are using GLM within a web application and outputs from GLM simulations are being passed between clients and servers. Saving outputs of GLM simulations to JSON format is useful if you want to render results in a web browser, for example.

Returns:

Type	Description
str Path to zipfile of GLM outputs.

zip_outputs()

Creates a zipfile of GLM outputs (csv and netcdf outputs).

Returns:

Type	Description
str Path to zipfile of GLM outputs.

GLMSim

Prepare inputs and run a GLM simulation.

The GLMSim class has attributes and methods that handle running GLM simulations and processing the results.

The class is designed to work with GLM simulations running on local instances of GLM or instances of GLM behind a FastAPI web API (i.e. when running GLM simulations as a web service). When running GLM locally input files required for a simulation (e.g. glm3.nml, met.csv) should be passed in as dict object with the format: {"<filename>": "<path-to-file>"}. When running GLM behind a web API, input files can be sent to the server from a client through a HTTP request and will be processed as a FastAPIUploadFile` object: https://fastapi.tiangolo.com/tutorial/request-files/#uploadfile

Attributes:

Name	Type	Description
input_files	Union[UploadFile, dict]	FastAPI UploadFile object storing input files for a GLM simulation or, if running GLM locally or outside a FastAPI environment a dict of filenames (keys) and paths to files (values).
api	bool	If True, GLM is run using FastAPI engine. Otherwise, local GLM versions.
inputs_dir	str	File path to directory to save input files for GLM simulation.

Examples:

Running GLM as a web service behind a FastAPI endpoint. files is a FastAPI UploadFile object.

>>> import glmpy.simulation as sim
>>> glm_sim = sim.GLMSim(files, True, "/inputs")
>>> inputs_dir = glm_sim.prepare_inputs()
>>> glm_sim.glm_run(inputs_dir, "/glm/glm")

Running GLM locally. files is a dict object with paths to where input files are stored.

>>> import glmpy.simulation as sim
>>> files = {
>>>    "glm3.nml": "/path/to/glm3.nml",
>>>    "met.csv": "/path/to/met.csv"
>>> }
>>> glm_sim = sim.GLMSim(files, False, "/inputs")
>>> inputs_dir = glm_sim.prepare_inputs()
>>> glm_sim.glm_run(inputs_dir, "/glm/glm")

bundled_glm_path() staticmethod

Path of the bundled GLM executable.

Returns the path of the internally bundled GLM executable. If the executable does not exist in the expected path, bundled_glm_path() returns None.

glm_run(inputs_dir, glm_path=None)

Run a GLM simulation.

Parameters:

Name	Type	Description	Default
inputs_dir	str	File path to directory with input files required for a GLM simulation.	required
glm_path	Union[str, None]	Path to location of GLM binary. If None, the internally bundled GLM executable will be called.	None

prepare_inputs()

Prepare input files for a GLM simulation.

If inputs_dir exists, it will be deleted and a new directory created with new input files.

Returns:

Type	Description
str	File path to directory with input files required for a GLM simulation.