API reference¶
This page provides an auto-generated summary of pysumma’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.
Simulation¶
-
class
pysumma.simulation.
Simulation
(executable, filemanager)[source]¶ The Simulation object provides a wrapper for SUMMA simulations. It can be used to set up, modify, and run SUMMA. The Simulation object consists of information about how to run SUMMA (the location of the executable, various command line flags and options) as well as configuration details which describe the domain to be simulated.
A standard workflow for running a simulation locally is:
import pysumma as ps s = ps.Simulation('summa.exe', 'file_manager.txt') s.start('local') s.monitor() assert s._status == 'Success' print(s.output)
A standard workflow for running a simulation through docker is:
import pysumma as ps s = ps.Simulation('summa:develop', 'file_manager.txt') s.start('docker') s.monitor() assert s._status == 'Success' print(s.output)
Parameters: - executable – Path to locally compiled SUMMA executable or the name of the docker image to run
- filemanager – Path to the file manager for the desired simulation setup. Can be specified as a relative path.
-
execute
(run_option, run_suffix=None, preprocess_cmds=[], monitor=False)[source]¶ Run a SUMMA simulation
-
monitor
()[source]¶ Watch a running simulation until it is done and collect the run information in the simulation object. This will halt execution of a started simulation through the
Simulation.start()
method.
-
output
¶ An xarray dataset, or list of xarray datasets representing the output that a simulation has written to disk.
-
result
¶ Attribute describing whether a model run was a success or not
-
start
(run_option, run_suffix='pysumma_run', processes=1, prerun_cmds=None, startGRU=None, countGRU=None, iHRU=None, freq_restart=None, progress=None)[source]¶ Start a SUMMA simulation. By default does not halt execution of further python commands, and simply launches the SUMMA process in the background. Progress can be halted by using the
Simulation.monitor()
method.Parameters: - run_option (string) – The method to use for running SUMMA, can be either
local
ordocker
. - run_suffix (string) – A unique identifier to include as part of the output file names
- processes (string) – The number of processors to use. Note: This only matters if the SUMMA version being run is compiled with OpenMP support. Defaults to 1.
- prerun_cmds (List[string]) – A list of commands to be run before the SUMMA executable is invoked. This can be used to set things like library paths or creation of subdirectories.
- startGRU (int) – The GRU index to start the simulation at. Used to run only
specified sections of the domain. Must be co-specified with
countGRU
to do anything. Cannot be used withiHRU
. - countGRU (int) – Number of GRU to run, starting at
startGRU
. Used to run only the specified portion of the domain. Must be co- specified withstartGRU
to do anything. Cannot be used withiHRU
. - iHRU (int) – Index of a single HRU to be run. Cannot be used with
startGRU
andcountGRU
. - freq_restart (string) – How often to write restart files. Can be
d
for daily,m
for monthly, andy
for yearly. - progress (string) – How often to record progress. Can be
d
for daily,m
for monthly, andy
for yearly.
- run_option (string) – The method to use for running SUMMA, can be either
-
stderr
¶ The standard error. This contains a string representation of the output that a SUMMA simulation would write to screen if any unforseen errors occurred. Use print to view this so that line breaks are rendered correctly.
-
stdout
¶ The standard output. This contains a string representation of the output that a SUMMA simulation would write to screen. Use print to view this so that line breaks are rendered correctly.
Ensemble¶
-
class
pysumma.ensemble.
Ensemble
(executable: str, filemanager: str, configuration: dict, num_workers: int = 1)[source]¶ Ensembles represent multiple SUMMA configurations based on changing the decisions file or parameter values. At it’s core, the Ensemble class is a thin wrapper around multiple Simulation objects, whos execution is managed by a dask
Client
.A standard workflow for running an ensemble is:
import pysumma as ps param_options = { 'fixedThermalCond_snow': np.arange(0.35, 0.85, 0.05) } config = ps.ensemble.parameter_product(param_options) # initialize and start runs e = ps.Ensemble(summa_exe, file_manager, config, num_workers=len(config)) e.start('local', arg_list=['export OMP_NUM_THREADS=1', 'export LD_LIBRARY_PATH=/opt/local/lib']) e.monitor() # check status for i, (n, s) in enumerate(e.simulations.items()): assert s._status == 'Success' # open output ds = e.merge_output()
Parameters: - executable (string) – Path to locally compiled SUMMA executable or the name of the docker image to run
- filemanager (string) – Path to the file manager for the desired simulation setup. Can be specified as a relative path
-
monitor
()[source]¶ Watch a running ensemble until it is done and collect the run information in the list of simulation objects. This will halt execution of a started simulation through the
Ensemble.start()
method ifmonitor
was not set there.
-
start
(run_option: str, arg_list: list = [], monitor: bool = False)[source]¶ Start running the ensemble. By default does not halt execution of further python commands, and simply launches the processes in the background. Progress can be halted by setting the
monitor
keyword.Parameters: - run option (string) – The method to use for running SUMMA. Can be either
local
ordocker
. - arg_list (List[string]) – A list of commands to be run before the simulations are started.
- monitor (bool) – Whether to halt execution until completion of all of
the simulations. Defaults to
False
- run option (string) – The method to use for running SUMMA. Can be either
-
pysumma.ensemble.
decision_product
(list_config)[source]¶ Create an Ensemble compatible configuration dictionary which contains the Cartesian product of the options given. For example:
decisions_options = { 'veg_traits': ['Raupach_BLM1994', 'CM_QJRMS1988'], 'cIntercept': ['sparseCanopy', 'storageFunc'], } ps.ensemble.decision_product(decisions_options)
will produce 4 runs in a configuration that looks like:
{'++Raupach_BLM1994++sparseCanopy++': {'decisions': {'veg_traits': 'Raupach_BLM1994', 'cIntercept': 'sparseCanopy'}}, '++Raupach_BLM1994++storageFunc++': {'decisions': {'veg_traits': 'Raupach_BLM1994', 'cIntercept': 'storageFunc'}}, '++CM_QJRMS1988++sparseCanopy++': {'decisions': {'veg_traits': 'CM_QJRMS1988', 'cIntercept': 'sparseCanopy'}}, '++CM_QJRMS1988++storageFunc++': {'decisions': {'veg_traits': 'CM_QJRMS1988', 'cIntercept': 'storageFunc'}}}
-
pysumma.ensemble.
parameter_product
(list_config)[source]¶ Create an Ensemble compatible configuration dictionary which contains the Cartesian product of the options given. For example:
param_options = { 'leafExchangeCoeff': np.arange(0.025, 0.0354, 0.01), 'albedoMax': np.arange(0.9, 0.96, 0.05) } ps.ensemble.parameter_product(param_options)
will produce 4 runs in a configuration that looks like:
{'++leafExchangeCoeff=0.025++albedoMax=0.9++': {'parameters': {'leafExchangeCoeff': 0.025, 'albedoMax': 0.9}}, '++leafExchangeCoeff=0.025++albedoMax=0.95++': {'parameters': {'leafExchangeCoeff': 0.025, 'albedoMax': 0.95}}, '++leafExchangeCoeff=0.035++albedoMax=0.9++': {'parameters': {'leafExchangeCoeff': 0.035, 'albedoMax': 0.9}}, '++leafExchangeCoeff=0.035++albedoMax=0.95++': {'parameters': {'leafExchangeCoeff': 0.035, 'albedoMax': 0.95}}}
-
pysumma.ensemble.
total_product
(dec_conf=None, param_conf=None)[source]¶ Create an Ensemble compatible configuration dictionary which contains the Cartesian product of the options given. For example:
param_options = { 'leafExchangeCoeff': np.arange(0.025, 0.0354, 0.01), } decisions_options = { 'veg_traits': ['Raupach_BLM1994', 'CM_QJRMS1988'], } ps.ensemble.total_product(decisions_options, param_options)
will produce 4 runs in a configuration that looks like:
{'++Raupach_BLM1994++leafExchangeCoeff=0.025++': {'decisions': {'veg_traits': 'Raupach_BLM1994'}, 'parameters': {'leafExchangeCoeff': 0.025}}, '++Raupach_BLM1994++leafExchangeCoeff=0.035++': {'decisions': {'veg_traits': 'Raupach_BLM1994'}, 'parameters': {'leafExchangeCoeff': 0.035}}, '++CM_QJRMS1988++leafExchangeCoeff=0.025++': {'decisions': {'veg_traits': 'CM_QJRMS1988'}, 'parameters': {'leafExchangeCoeff': 0.025}}, '++CM_QJRMS1988++leafExchangeCoeff=0.035++': {'decisions': {'veg_traits': 'CM_QJRMS1988'}, 'parameters': {'leafExchangeCoeff': 0.035}}}
Decisions¶
-
class
pysumma.decisions.
DecisionOption
(name, value)[source]¶ Bases:
pysumma.option.BaseOption
Container for lines in a decisions file
-
class
pysumma.decisions.
Decisions
(path)[source]¶ Bases:
pysumma.option.OptionContainer
The Decisions object provides an interface to a SUMMA decisions file.
-
clear
()¶ Clear all options
-
get_option
(name, strict=False)¶ Retrieve an option
Parameters: - name ((string)) – The name of the option to search for
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
get_value
(name, strict=False)¶ Retrieve the value of a given option
Parameters: - name ((string)) – The name of the option whose value to search for
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
read
(path)¶ Read the configuration and populate the options
-
remove_option
(name, strict=False)¶ Remove an option
Parameters: - name ((string)) – The name of the option whose value to remove
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
validate
()¶ Ensure no options are repeated
-
write
(path=None)¶ Write the configuration based on the string representation of the OptionType of the instance.
Parameters: path ((string, optional)) – Where to write the file. If not provided the original file will be overwritten.
-
Output Control¶
-
class
pysumma.output_control.
OutputControl
(path)[source]¶ Bases:
pysumma.option.OptionContainer
The OutputControl object manages what output SUMMA will write out. Each output variable is stored in the options list as an OutputControlOption. These options are automatically populated on instantiation, and can be added or modified through the set_option method.
-
clear
()¶ Clear all options
-
get_option
(name, strict=False)¶ Retrieve an option
Parameters: - name ((string)) – The name of the option to search for
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
get_value
(name, strict=False)¶ Retrieve the value of a given option
Parameters: - name ((string)) – The name of the option whose value to search for
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
read
(path)¶ Read the configuration and populate the options
-
remove_option
(name, strict=False)¶ Remove an option
Parameters: - name ((string)) – The name of the option whose value to remove
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
set_option
(name=None, period=None, sum=0, instant=1, mean=0, variance=0, min=0, max=0, mode=0)[source]¶ Change or create a new entry in the output control
-
validate
()¶ Ensure no options are repeated
-
write
(path=None)¶ Write the configuration based on the string representation of the OptionType of the instance.
Parameters: path ((string, optional)) – Where to write the file. If not provided the original file will be overwritten.
-
-
class
pysumma.output_control.
OutputControlOption
(var=None, period=None, sum=0, instant=1, mean=0, variance=0, min=0, max=0, mode=0)[source]¶ Bases:
pysumma.option.BaseOption
-
statistic
¶ This could be improved
-
Local Param Info¶
-
class
pysumma.local_param_info.
LocalParamInfo
(path)[source]¶ Bases:
pysumma.option.OptionContainer
-
clear
()¶ Clear all options
-
get_option
(name, strict=False)¶ Retrieve an option
Parameters: - name ((string)) – The name of the option to search for
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
get_value
(name, strict=False)¶ Retrieve the value of a given option
Parameters: - name ((string)) – The name of the option whose value to search for
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
remove_option
(name, strict=False)¶ Remove an option
Parameters: - name ((string)) – The name of the option whose value to remove
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
validate
()¶ Ensure no options are repeated
-
write
(path=None)¶ Write the configuration based on the string representation of the OptionType of the instance.
Parameters: path ((string, optional)) – Where to write the file. If not provided the original file will be overwritten.
-
-
class
pysumma.local_param_info.
LocalParamOption
(name, default, low, high)[source]¶ Bases:
pysumma.option.BaseOption
Basin Param Info¶
Option¶
-
class
pysumma.option.
BaseOption
(name, value=None)[source]¶ Base implementation for representing options in the various text based SUMMA configuration files. This class is meant to be extended rather than used directly.
-
class
pysumma.option.
OptionContainer
(path, optiontype)[source]¶ Base implementation for representing text based configuration files for SUMMA. This class is meant to be extended rather than used directly.
-
get_option
(name, strict=False)[source]¶ Retrieve an option
Parameters: - name ((string)) – The name of the option to search for
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-
get_value
(name, strict=False)[source]¶ Retrieve the value of a given option
Parameters: - name ((string)) – The name of the option whose value to search for
- strict ((bool, optional)) – Whether to raise an error if the option
is not found. Defaults to
False
, which does not raise exceptions.
-