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

Library

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

Session

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

Project

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

Library

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

Scenario

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

Library

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

Project

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

Scenario

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

Module contents