pysyncrosim package
Submodules
pysyncrosim.environment module
- pysyncrosim.environment.progress_bar(report_type='step', iteration=None, timestep=None, total_steps=None, message=None)
Begins, steps, ends, and reports progress for a SyncroSim simulation.
- Parameters
report_type (String, optional) – Directive to “begin”, “end”, “report”, “message”, or “step” the simulation. The default is “step”.
iteration (Int, optional) – Number of iterations. The default is None.
timestep (Int, optional) – Number of timesteps. The default is None.
total_steps (Int, optional) – Number of total steps in the simulation. The default is None.
message (String, optional) – A message to print to the progress bar status. The default is None.
- Raises
TypeError – If iteration, timestep, or total_steps are not Integers.
ValueError – If report_type is not “begin”, “end”, “step”, “report”, or “message”.
- Return type
None.
- pysyncrosim.environment.runtime_input_folder(scenario, datasheet_name)
Creates a SyncroSim Datasheet input folder.
- Parameters
scenario (Scenario) – Scenario class instance.
datasheet_name (String) – Name of SyncroSim Datasheet.
- Returns
Path to input folder.
- Return type
String
- pysyncrosim.environment.runtime_output_folder(scenario, datasheet_name)
Creates a SyncroSim Datasheet output folder.
- Parameters
scenario (Scenario) – Scenario class instance.
datasheet_name (String) – Name of SyncroSim Datasheet.
- Returns
Path to ouput folder.
- Return type
String
- pysyncrosim.environment.runtime_temp_folder(folder_name)
Creates a SyncroSim Datasheet temporary folder.
- Parameters
folder_name (String) – Name of temporary folder.
- Returns
Path to temporary folder.
- Return type
String
- pysyncrosim.environment.update_run_log(*message, sep='')
Begins, steps, ends, and reports progress for a SyncroSim simulation.
- Parameters
*message (String) – Message to write to the run log. Can be provided as multiple arguments that will be concatenated together using sep.
sep (String, optional) – String to use if concatenating multiple message arguments. The default is an empty String.
- Raises
ValueError – If no message is provided.
- Return type
None.
pysyncrosim.helper module
- pysyncrosim.helper.library(name, session=None, package='stsim', addons=None, template=None, forceUpdate=False, overwrite=False)
Creates a new SyncroSim Library and opens it as a Library class instance.
- Parameters
name (String) – Name of new Library to create.
session (Session, optional) – Connects the Python session to the SyncroSim executable. If None, then creates a Session class instance using the default installation path to the SyncroSim executable. The default is None.
package (String, optional) – The package type. The default is “stsim”.
addons (String or List of Strings, optional) – One or more addon packages. The default is None.
template (String, optional) – Creates Library with specified template. The default is None.
forceUpdate (Logical, optional) – If False, then user is prompted to approve required updates. The default is False.
overwrite (Logical, optional) – Overwrite existing Library. The default is False.
- Returns
SyncroSim Library class instance.
- Return type
pysyncrosim.library module
- class pysyncrosim.library.Library(location=None, session=None)
Bases:
object
A class to represent a SyncroSim Library.
- property addons
Retrieves the addon(s) this Library is using.
- Returns
Addon name(s).
- Return type
String
- backup()
Creates a backup of a SyncroSim Library.
- Return type
None.
- datasheets(name=None, summary=True, optional=False, empty=False, scope='Library', filter_column=None, filter_value=None, include_key=False, show_full_paths=True, return_hidden=False, *ids)
Retrieves a DataFrame of Library Datasheets.
- Parameters
name (String, optional) – Datasheet name. The default is None.
summary (Logical or String, optional) – Whether to list package Datasheets or core Datasheets. The default is True.
optional (Logical, optional) – Return optional columns. The default is False.
empty (Logical, optional) – Return an empty Datasheet. The default is False.
scope (String, optional) – Datasheet scope. Options include “Library”, “Project”, or “Scenario”. The default is “Library”.
filter_column (String) – The column to filter the output Datasheet by. The default is None.
filter_value (String, Int, or Logical) – The value to filter the filter_column by. The default is None.
include_key (Logical, optional) – Whether to include the primary key of the Datasheet, corresponding to the SQL database. Default is False.
show_full_paths (Logical, optional) – If set to True, returns the full path of any external files in the Datasheet. Default is True.
return_hidden (Logical, optional) – If set to True, returns all records in a Datasheet, including those hidden from the user. Results in a slower query. Default is False.
- Returns
If optional=False, then returns a DataFrame of Datasheet information including Package, Name, and Display Name. If optional=True, also returns Scope, Is Single, and Is Output.
- Return type
pandas.DataFrame
- property date_modified
Retrieves the last date this Library was modified.
- Returns
Last date modified.
- Return type
String
- delete(project=None, scenario=None, force=False)
Deletes a SyncroSim class instance.
- Parameters
project (Project, String, or Int, optional) – If called from a Library class instance, specify the Project to delete. The default is None.
scenario (Scenario, String, or Int, optional) – If called from a Scenario class instance, specify the Scenario to delete. The default is None.
force (Logical, optional) – If set to True, does not ask user before deleting SyncroSim class instance. The default is False.
- Return type
None.
- property description
Gets or sets the description for this Library.
- Returns
Library description.
- Return type
String
- disable_addons(name)
Disable addon package(s) of a SyncroSim Library.
- Parameters
name (String) – Name of addon package(s).
- Raises
ValueError – addon does not exist in available addons for this Library.
- Return type
None.
- enable_addons(name)
Enable addon package(s) of a SyncroSim Library.
- Parameters
name (String or List) – Name of addon(s).
- Raises
ValueError – addon does not exist in available addons for this Library.
- Return type
None.
- property info
Retrieves information about this Library.
- Returns
General library information.
- Return type
pd.DataFrame
- property location
Retrieves the file path to this Library.
- Returns
Library file path.
- Return type
String
- property name
Retrieves or sets the name of this Library.
- Returns
Library name.
- Return type
String
- property owner
Gets or sets the owner of this Library.
- Returns
Owner of this Library.
- Return type
String
- property package
Retrieves the package this Library is using.
- Returns
Package name.
- Return type
String
- projects(name=None, pid=None, summary=True, overwrite=False)
Creates or opens one or more SyncroSim Projects in the Library.
- Parameters
name (String, optional) – Name of Project. The default is None.
pid (Int, optional) – Project ID. The default is None.
summary (Logical, optional) – If True, returns a DataFrame of Project information. If False, returns a list of Project objects. Default is True.
overwrite (Logical, optional) – If True, then overwrites an existing Project. Default is False.
- Returns
DataFrame containing Project information, including ID, Name, Owner, Last Modified, and Read Only, or List of Projects if summary=False.
- Return type
Project, List of Projects, or pandas.DataFrame
- property readonly
Gets or sets the read-only status of this Library.
- Returns
“yes” if this Project is read-only, “no” otherwise.
- Return type
String
- run(scenarios=None, project=None, jobs=1, copy_external_inputs=False)
Runs a list of Scenario objects.
- Parameters
scenarios (Scenario, String, Int, or List) – List of Scenrios, SyncroSim Scenario instance, name of Scenario, or Scenario ID.
project (Project, optional) – SyncroSim Project instance, name of Project, or Project ID.
jobs (Int, optional) – Number of multiprocessors to use. The default is 1.
copy_external_inputs (Logical, optional) – If False, then a copy of external input files (e.g. GeoTIFF files) is not created for each job. Otherwise, a copy of external inputs is created for each job. Applies only when jobs > 1. The default is False.
- Returns
result_dict – Dictionary of Results Scenarios.
- Return type
Dictionary
- save_datasheet(name, data, append=False, force=False, scope='Library', *ids)
Saves a pandas DataFrane as a SyncroSim Datasheet.
- Parameters
name (String) – Name of the Datasheet.
data (pandas DataFrame) – DataFrame of Datasheet values.
append (Logical, optional) – If set to True, appends the DataFrame to the existing Datasheet (if the Datasheet accepts multiple rows). If False, then the user must also specify force as True to overwrite the existing Datasheet. Default is False.
force (Logical, optional) – If set to True while append is False, overwrites the existing Datasheet. The user should be aware that this may also delete other definitions and results, so this argument should be used with care. Default is False.
scope (String, optional) – Scope of the Datasheet. The default is “Library”.
*ids (Int) – If Project- or Scenario-scoped, requires the Project or Scenario IDs.
- Return type
None.
- scenarios(name=None, project=None, sid=None, pid=None, overwrite=False, optional=False, summary=None, results=False)
Retrieves a Scenario or DataFrame of Scenarios in this Library.
- Parameters
name (String, Int, or List of these, optional) – Scenario name. If an integer is given, the value will be parsed as as Scenario ID. The default is None.
project (Project, String, or Int, optional) – Project the Scenario belongs to. If no Project is specified when creating a new Scenario, the “Definitions” default Project is used. The default is None.
sid (Int or List of Ints, optional) – Scenario ID. If both name and sid are specified, the sid is used. The default is None.
pid (Int, optional) – Project ID. The default is None.
overwrite (Logical, optional) – Overwrites an existing Scenario. The default is False.
optional (Logical, optional) – Return optional information. The default is False.
summary (Logical, optional) – When name and sid is None, if True, returns a DataFrame of information on existing Scenarios. Otherwise returns a list of Scenario class instances.
results (Logical, optional) – Return only a list of Results Scenarios. The default is False.
- Returns
If a name or sid is specified, returns a Scenario class instance. If no name or sid is specified, and summary is set to False, returns a list of Scenario class instances. If no name or sid is specified and summary is set to True, returns a pandas.DataFrame of Scenario information for this Library.
- Return type
Scenario, List of Scenarios, or pandas.DataFrame
- property session
Retrieves the Session associated with this Library.
- Returns
The Session for this Library.
- Return type
- update()
Updates a SyncroSim Library.
- Return type
None.
pysyncrosim.project module
- class pysyncrosim.project.Project(pid, name, library)
Bases:
object
A class to represent a SyncroSim Project.
- copy(name=None)
Creates a copy of an existing Project.
- Parameters
name (String, optional) – Name of the new Project. If no name is given, the copied Project is named after the source Project. The default is None.
- Returns
SyncroSim Project class instance.
- Return type
- datasheets(name=None, summary=True, optional=False, empty=False, filter_column=None, filter_value=None, include_key=False, show_full_paths=True, return_hidden=False)
Retrieves a DataFrame of Project Datasheets.
- Parameters
name (String, optional) – Datasheet name. The default is None.
summary (Logical or String, optional) – Whether to list package Datasheets or core Datasheets. The default is True.
optional (Logical, optional) – Return optional columns. The default is False.
empty (Logical, optional) – If True, returns an empty Datasheet. The default is False.
filter_column (String) – The column and value to filter the output Datasheet by (e.g. “TransitionGroupID=20”). The default is None.
include_key (Logical, optional) – Whether to include the primary key of the Datasheet, corresponding to the SQL database. Default is False.
show_full_paths (Logical, optional) – Whether to show the full path of any external files in the Datasheet. Default is True.
return_hidden (Logical, optional) – If set to True, returns all records in a Datasheet, including those hidden from the user. Results in a slower query. Default is False.
- Returns
If optional=False, then returns a DataFrame of Datasheet information including Package, Name, and Display Name. If optional=True, also returns Scope, Is Single, and Is Output.
- Return type
pandas.DataFrame
- property date_modified
Gets the last date this Project was modified.
- Returns
Last date modified.
- Return type
String
- delete(scenario=None, force=False)
Deletes a Project or Scenario.
- Parameters
scenario (Scenario, String, or Int, optional) – Scenario to delete. The default is None.
force (Logical, optional) – If True, does not prompt the user to confirm deletion. The default is False.
- Return type
None.
- property description
Gets or sets the Project description.
- Returns
Project description.
- Return type
String
- property info
Retrieves Project information.
- Returns
Project information.
- Return type
pandas DataFrame
- property library
Retrieves the Library the Project belongs to.
- Returns
SyncroSim Library class instance.
- Return type
- property name
Retrieves or sets Project name.
- Returns
Project name.
- Return type
String
- property owner
Gets or sets the owner of this Project.
- Returns
Owner of this Project.
- Return type
String
- property pid
Retrieves Project ID.
- Returns
Project ID.
- Return type
Int
- property readonly
Gets or sets the read-only status for this Project.
- Returns
“yes” if this Project is read-only, “no” otherwise.
- Return type
String
- run(scenarios=None, jobs=1, copy_external_inputs=False)
Runs a list of Scenario objects.
- Parameters
scenarios (Scenario, String, Int, or List) – List of Scenrios, SyncroSim Scenario instance, name of Scenario, or Scenario ID.
jobs (Int, optional) – Number of multiprocessors to use. The default is 1.
copy_external_inputs (Logical, optional) – If False, then a copy of external input files (e.g. GeoTIFF files) is not created for each job. Otherwise, a copy of external inputs is created for each job. Applies only when jobs > 1. The default is False.
- Returns
result_dict – Dictionary of Results Scenarios.
- Return type
Dictionary
- save_datasheet(name, data, append=True, force=False)
Saves a Project-scoped Datasheet.
- Parameters
name (String) – Name of Datasheet to save.
data (pandas.DataFrame) – DataFrame to save as Datasheet.
append (Logical, optional) – If True, appends to existing Datasheet. If False, then the user must also specify force=True to overwrite the existing Datasheet. The default is True.
force (Logical, optional) – If True, overwrites existing Datasheet. The user should be aware that this may also delete other definitions and results, so this argument should be used with care. The default is False.
- Return type
None.
- scenarios(name=None, sid=None, optional=False, summary=None, results=False)
Retrieve a DataFrame of Scenarios in this Project.
- Parameters
name (String, optional) – Scenario name. The default is None.
sid (Int, optional) – Scenario ID. The default is None.
optional (Logical, optional) – Return optional information. The default is False.
summary (Logical, optional) – If set to False, then returns all Scenarios as SyncroSim Scenario instances. The default is None.
results (Logical, optional) – Return only a list of Results Scenarios. The default is False.
- Returns
If optional=False, then returns a DataFrame of Scenario information including Scenario ID, Project ID, Name, and Is Result. If optional=True, also returns Parent ID, Owner, Last Modified, Read Only, Merge Dependencies, Ignore Dependencies, and Auto Gen Tags.
- Return type
pandas.DataFrame
pysyncrosim.raster module
- class pysyncrosim.raster.Raster(source, iteration=None, timestep=None)
Bases:
object
A class to represent a raster object.
- property crs
Gets the coordinate system of the raster
- property dimensions
Gets the dimensions of the raster
- property extent
Gets the extent of the raster
- property name
Gets the name of the raster
- property resolution
Gets the resolution of the raster
- property source
Gets the filepath of the raster
- values(band=None)
Gets the values in each cell of the raster
- Parameters
band (Int, optional) – The specific band to return. If None, then all bands in the raster are returned in the array, with the first dimension of the array corresponding to the band number. The default is None.
- Returns
values – Array of values corresponding to the cell values in the raster.
- Return type
numpy array
pysyncrosim.scenario module
- class pysyncrosim.scenario.Scenario(sid=None, name=None, project=None, library=None)
Bases:
object
A class representing a SyncroSim Scenario.
- copy(name=None)
Creates a copy of an existing Scenario class instance.
- Parameters
name (String) – Name of the new Scenario. If no name is provided, the copied Scenario is named after the existing Scenario. The default is None.
- Returns
SyncroSim Scenario class instance.
- Return type
- datasheet_rasters(datasheet, column=None, iteration=None, timestep=None, filter_column=None, filter_value=None, path_only=False)
Retrieves spatial data columns from one or more SyncroSim Datasheets.
- Parameters
datasheet (String) – The name of a SyncroSim Datasheet containing raster data.
column (String) – The column in the Datasheet containing the raster data. If no column selected, then datasheet_rasters will attempt to find one.
iteration (Int, List, or Range, optional) – The iteration to subset by. The default is None.
timestep (Int, List, or Range, optional) – The timestep to subset by. The default is None.
filter_column (String) – The column to filter the output rasters by (e.g. “TransitionGroupID=20”). The default is None.
filter_value (String, Int, Logical) – The value to filter the filter_column by. The default is None.
path_only (Logical) – Instead of returning a Raster Class Instance, a filepath to the raster is returned. The default is False.
- Returns
Raster class instance or List of these.
- Return type
Raster or List of Rasters
- datasheets(name=None, summary=True, optional=False, empty=False, filter_column=None, filter_value=None, include_key=False, show_full_paths=True, return_hidden=False)
Retrieves a DataFrame of Scenario Datasheets.
- Parameters
name (String, optional) – Datasheet name. The default is None.
summary (Logical or String, optional) – Whether to list package Datasheets or core Datasheets. The default is True.
optional (Logical, optional) – Return optional columns. The default is False.
empty (Logical, optional) – If True, returns an empty Datasheet. The default is False.
filter_column (String) – The column and value to filter the output Datasheet by (e.g. “TransitionGroupID=20”). The default is None.
include_key (Logical, optional) – Whether to include the primary key of the Datasheet, corresponding to the SQL database. Default is False.
show_full_paths (Logical, optional) – Whether to show the full path of any external files in the Datasheet. Default is True.
return_hidden (Logical, optional) – If set to True, returns all records in a Datasheet, including those hidden from the user. Results in a slower query. Default is False.
- Returns
If optional=False, then returns a DataFrame of Datasheet information including Package, Name, and Display Name. If optional=True, also returns Scope, Is Single, and Is Output.
- Return type
pandas.DataFrame
- property date_modified
Gets the last date this Scenario was modified.
- Returns
Last date modified.
- Return type
String
- delete(force=False)
Deletes a Scenario.
- Parameters
force (Logical, optional) – If True, does not ask the user for permission to delete the Scenario. The default is False.
- Return type
None.
- dependencies(dependency=None, remove=False, force=False)
Gets, sets, or removes dependencies from a Scenario.
- Parameters
dependency (Scenario, Int, String, or List, optional) – Scenario(s) to be added or removed as dependencies. If None, then returns a DataFrame of dependencies. The default is None.
remove (Logical, optional) – If False, adds the dependency. If True, removes the dependency. The default is False.
force (Logical, optional) – If True, then does not prompt the user when removing a dependency. The default is False.
- Raises
TypeError – If arguments are not of the correct Type, throws an error.
- Returns
If no dependencies are specified, then returns a pandas DataFrame of existing dependencies for the given Scenario.
- Return type
pandas.DataFrame
- property description
Gets or sets the Scenario description.
- Returns
Scenario description.
- Return type
String
- ignore_dependencies(value=None)
Retrieves or sets the Datafeeds to ignore for a Scenario.
- Parameters
value (String, optional) – Datafeeds to ignore. If more than one, separate with a comma, but keep contained within the same String. If None, then a String of Datafeeds to ignore is returned. The default is None.
- Returns
List of Datafeeds to ignore.
- Return type
String
- property info
Retrieves Scenario information.
- Returns
Scenario information.
- Return type
pandas DataFrame
- property is_result
Retrieves information about whether this Scenario is a Results Scenario or not.
- Returns
Whether Scenario is a Results Scenario.
- Return type
Logical
- property library
Retrieves Library class instance associated with this Library.
- Returns
SyncroSim Library class instance.
- Return type
- merge_dependencies(value=None)
Retrieves or sets whether or not a Scenario is configured to merge dependencies at run time.
- Parameters
value (Logical, optional) – If True, the Scenario will be configured to merge dependencies at run time. If None, then the current configuration of merge dependencies is returned. The default is None.
- Returns
Whether or not the Scenario is configured to merge dependencies at run time.
- Return type
String
- property name
Retrieves or sets a Scenario name.
- Parameters
Value (String) – New Scenario name.
- Returns
Scenario name.
- Return type
String
- property owner
Gets or sets the owner of this Scenario.
- Returns
Owner of this Scenario.
- Return type
String
- property parent_id
Retrieves the ID of the parent Scenario of a Results Scenario.
- Returns
Parent ID of a Results Scenario.
- Return type
Int
- property project
Retrieves Project class instance associated with this Scenario.
- Returns
SyncroSim Project class instance.
- Return type
- property project_id
Gets the Project ID associated with this Scenario.
- Returns
Project ID.
- Return type
Integer
- property readonly
Gets or sets the read-only status for this Scenario.
- Returns
“yes” if this Scenario is read-only, “no” otherwise.
- Return type
String
- results(sid=None)
Retrieves DataFrame of Results Scenarios or retrieves a Results Scenario instance for this Scenario.
- Parameters
sid (Int, optional) – Scenario ID of Results Scenario. Default is None.
- Returns
DataFrame of Results Scenarios, including information about Scenario ID, Project ID, Name, and Is Result, or SyncroSim Scenario class instance.
- Return type
pandas.DataFrame or Scenario
- run(jobs=1, copy_external_inputs=False)
Runs a Scenario.
- Parameters
jobs (Int, optional) – Number of multiprocessors to use when running a Scenario. The default is 1.
copy_external_inputs (Logical, optional) – If False, then a copy of external input files (e.g. GeoTIFF files) is not created for each job. Otherwise, a copy of external inputs is created for each job. Applies only when jobs > 1. The default is False.
- Returns
SyncroSim Scenario class instance.
- Return type
- run_log()
Returns a run log for a Results Scenario.
- Returns
Information from the SyncroSim run of a Results Scenario.
- Return type
pandas.DataFrame
- save_datasheet(name, data, append=False)
Saves a pandas DataFrame as a SyncroSim Datasheet.
- Parameters
name (String) – Name of the SyncroSim Datasheet.
data (pandas.DataFrame) – Data to be saved to SyncroSim Datasheet.
append (Logical, optional) – If True, appends data to existing Datasheet. The default is False.
- Return type
None.
- property sid
Retrieves Scenario ID.
- Returns
Scenario ID.
- Return type
Int
pysyncrosim.session module
- class pysyncrosim.session.Session(location=None, silent=True, print_cmd=False)
Bases:
object
A class to represent a SyncroSim Session.
- add_packages(packages)
Installs a package.
- Parameters
packages (List or String) – Name or list of names of packages to install. Can also be a filepath (or list of filepaths) to a local package.
- Return type
None.
- property location
Retrieves the location for this Session.
- Returns
Filepath to SyncroSim Session.
- Return type
String
- packages(installed=True)
Retrieves DataFrame of installed packages.
- Parameters
installed (Logical or String, optional) – If False, then shows all available packages. If “BASE”, only shows installed base packages. If True, then shows installed addons in addition to base packages. The default is True.
- Returns
pkgs – DataFrame listing the Name, Display Name, and Version of all installed base packages.
- Return type
pandas.DataFrame
- property print_cmd
Gets or sets the print_cmd status of the SyncroSim Session.
- Returns
print_cmd status.
- Return type
Logical
- remove_packages(packages)
Uninstalls a package.
- Parameters
packages (List or String) – Name or list of names of packages to uninstall.
- Return type
None.
- property silent
Gets or sets the silent status for this Session.
- Returns
Silent status.
- Return type
Logical
- update_packages(packages=None)
Updates a package to the newest version.
- Parameters
packages (List or String) – Name or list of names of packages to update. If None, then updates all packages. Default is None.
- Return type
None.
- version()
Retrieves SyncroSim version.
- Returns
Version number.
- Return type
String