API reference

This page provides an auto-generated summary of pysumma’s API. For more details and examples, refer to the main documentation.

Simulation

class pysumma.Simulation(executable, filemanager, initialize=True, config_dir='.pysumma')

The simulation object provides a wrapper for SUMMA simulations

stdout

Store standard output of the run

stderr

Handle to the process during runtime

manager_path

Path to the file manager

config_path

Path to where configuration will be written

status

Current status of the simulation

manager

File manager object (populated after calling initialize)

decisions

Decisions object (populated after calling initialize)

output_control

OutputControl object (populated after calling initialize)

trial_params

Spatially distributed parameters (populated after calling initialize)

force_file_list

ForcingList object (populated after calling initialize)

global_hru_params

GlobalParams object for hru (populated after calling initialize)

global_gru_params

GlobalParams object for gru (populated after calling initialize)

local_attributes

LocalAttributes object (populated after calling initialize)

initial_conditions

InitialConditions object (populated after calling initialize)

apply_config(config: dict)

Change the settings of the simulation based on a configuration dictionary.

Parameters:

config – A dictionary where keys represent the type of change and the values represent the changes to be applied. A representative example might be:

:: config = {

‘file_manager’: ‘/home/user/cool_setup/file_manager_new.txt’, ‘decisions’: {‘snowLayers’: ‘CLM_2010’}, ‘parameters’: {‘albedoDecayRate’: 1e-6}, ‘trial_parameters’: {‘theta_mp’: 0.4}, ‘attributes’: {‘mHeight’: 15} }

assign_attributes(name, data)

Assign new data to the local_attributes dataset.

Parameters:

• name – The name (or key) of the attribute to modify
• data – The data to change the attribute to. The shape must match the shape in the local attributes file

assign_trial_params(name, data, dim='hru', create=True)

Assign new data to the spatial_params dataset.

Parameters:

• name – The name (or key) of the attribute to modify
• data – The data to change the parameter to. The shape must match the shape in the parameter trial file

get_output_files() → List[str]

Find output files given the stdout generated from a run

initialize()

Initialize reads in all of the relevant files. This may not be desired on instantiation, so the initialize parameter can be set in the constructor. Calling this will also create a backup of the configuration that can be restored via the reset method.

monitor()

Halt execution until Simulation either finishes or errors

output

Get the output as an xarray dataset

reset()

Restores the original settings of the Simulation

run(run_option, run_suffix='pysumma_run', processes=1, prerun_cmds=None, startGRU=None, countGRU=None, iHRU=None, freq_restart=None, progress=None, **kwargs)

Run a SUMMA simulation and halt until completion or error.

Parameters:

• run_option – Method to run SUMMA, must be one of either local or docker
• run_suffix – Name to append to the output files for this SUMMA run
• processes – Number of openmp processes to use for this run. For this to do anything SUMMA must be compiled with openmp support
• prerun_cmds – A list of commands to execute before running SUMMA. May be necessary to set environment variables or do any preprocessing
• startGRU – GRU index to start the simulation on (must also set countGRU if this argument is set)
• countGRU – Number of GRU to run, starting at startGRU (must also set startGRU if this argument is set)
• iHRU – Index of HRU to run (cannot be used with startGRU and countGRU)
• freq_restart – Frequency to write restart files. Options include [y, m, d, never] for yearly, monthly, and daily restart files. Defaults to never
• progress – Frequency to write stdout progress. Note this is not printed during runtime via pysumma, but can be checked after completion. Options include [m, d, h, never] for monthly, daily, and hourly output.

start(run_option, run_suffix='pysumma_run', processes=1, prerun_cmds=[], startGRU=None, countGRU=None, iHRU=None, freq_restart=None, progress=None, **kwargs)

Run a SUMMA simulation without halting. Most likely this should not be used. Use the run method for most common use cases.

validate_layer_params(params)

Ensure that the layer parameters are valid

Ensemble

class pysumma.Ensemble(executable: str, configuration: dict, filemanager: str = None, num_workers: int = 1, threads_per_worker: int = 1, scheduler: str = None, client: distributed.client.Client = None)

Ensembles represent an multiple SUMMA configurations based on changing the decisions or parameters of a given run.

executable

Path to the SUMMA executable

filemanager

Path to the file manager

Type:(optional)

configuration

Dictionary of runs, along with settings

num_workers

Number of parallel workers to use

simulations

Dictionary of run names and Simulation objects

merge_output()

Open and merge all of the output datasets from the ensemble run into a single dataset.

monitor()

Halt computation until submitted simulations are complete

open_output()

Open all of the output datasets from the ensembe and return as a dictionary of datasets

rerun_failed(run_option: str, prerun_cmds=None, monitor: bool = True)

Try to re-run failed simulations.

Parameters:

• run_option – Where to run the simulation. Can be local or docker
• prerun_cmds – A list of shell commands to run before running SUMMA
• monitor – Whether to halt operation until runs are complete

run(run_option: str, prerun_cmds=None, monitor: bool = True)

Run the ensemble

Parameters:

• run_option – Where to run the simulation. Can be local or docker
• prerun_cmds – A list of shell commands to run before running SUMMA
• monitor – Whether to halt operation until runs are complete

start(run_option: str, prerun_cmds: list = None)

Start running the ensemble members.

Parameters:

• run_option – The run type. Should be either ‘local’ or ‘docker’
• prerun_cmds – A list of preprocessing commands to run

summary()

Show the user information about ensemble status

Distributed

class pysumma.Distributed(executable: str, filemanager: str, num_workers: int = 1, threads_per_worker: int = 1, chunk_size: int = None, num_chunks: int = None, scheduler: str = None, client: distributed.client.Client = None)

Distributed objects represent SUMMA configurations where there are multiple GRU/HRU which are expected to be run in parallel.

Currently only supports GRU based parallelization.

executable

Path to the SUMMA executable

manager

FileManager object

num_workers

Number of parallel workers to use

chunk_args

List of dictionaries containing startGRU and countGRU values

simulations

Dictionary of run names and Simulation objects

monitor()

Halt computation until submitted simulations are complete

run(run_option: str, prerun_cmds=None, monitor: bool = True)

Run the ensemble

Parameters:

• run_option – Where to run the simulation. Can be local or docker
• prerun_cmds – A list of shell commands to run before running SUMMA
• monitor – Whether to halt operation until runs are complete

start(run_option: str, prerun_cmds: List[T] = None)

Start running the ensemble members.

Parameters:

• run_option – The run type. Should be either ‘local’ or ‘docker’
• prerun_cmds – A list of preprocessing commands to run