biosimulators_utils.simulator package¶
Submodules¶
biosimulators_utils.simulator.cli module¶
Utilities for creating BioSimulators-compliant command-line interfaces for biosimulation tools.
- Author
Jonathan Karr <karr@mssm.edu>
- Date
2020-12-04
- Copyright
2020, Center for Reproducible Biomedical Modeling
- License
MIT
- biosimulators_utils.simulator.cli.build_cli(cli_name=None, cli_version=None, simulator_name=None, simulator_version=None, simulator_url=None, combine_archive_executer=None, environment_variables=None)[source]¶
Create a BioSimulators-compliant command-line application for a biosimulation tool.
The command-line application will have two inputs
A path to a COMBINE/OMEX archive that describes one or more simulations or one or more models
A path to a directory to store the outputs of the execution of the simulations defined in the archive
The command-line application will also support two additional commands
A command for printing help information about the command-line application (-h, –help)
A command for printing version information about the command-line application (-v, –version)
- Parameters
cli_name (
str
) – name of the command-line program (e.g., copasi)cli_version (
str
, optional) – version of the command-line applicationsimulator_name (
str
) – name of the simulator (e.g., COPASI)simulator_version (
str
, optional) – version of the simulatorsimulator_url (
str
, optional) – URL for information about the simulatorcombine_archive_executer (
types.FunctionType
) – a function which has two positional arguments * The path to the COMBINE/OMEX archive * The path to the directory to save the outputs of the simulations defined in the archiveenvironment_variables (
list
ofEnvironmentVariable
, optional) – description of the environment variables recognized by the simulator
- Returns
command-line application
- Return type
cement.App
- Raises
SystemExit – if the execution of the COMBINE/OMEX archive fails
biosimulators_utils.simulator.data_model module¶
Data model for simulators
- Author
Jonathan Karr <karr@mssm.edu>
- Date
2020-12-06
- Copyright
2020, Center for Reproducible Biomedical Modeling
- License
MIT
- class biosimulators_utils.simulator.data_model.EnvironmentVariable(name=None, description=None, options=None, default=None, more_info_url=None)[source]¶
Bases:
object
Environment variable supported by a simulator
- name(
obj: str): name
- description(
obj: str): description
- options(
obj: type): enumeration of options
- default(
obj: str): default
- more_info_url(
obj: str): URL with more information about the variable
biosimulators_utils.simulator.environ module¶
Common environment variables for simulators
- Author
Jonathan Karr <karr@mssm.edu>
- Date
2020-12-29
- Copyright
2020, Center for Reproducible Biomedical Modeling
- License
MIT
biosimulators_utils.simulator.exceptions module¶
Standard exceptions issued by biosimulation tools
- Author
Jonathan Karr <karr@mssm.edu>
- Date
2020-12-29
- Copyright
2020, Center for Reproducible Biomedical Modeling
- License
MIT
- exception biosimulators_utils.simulator.exceptions.AlgorithmDoesNotSupportModelFeatureException[source]¶
Bases:
biosimulators_utils.exceptions.BioSimulatorsException
Exception that an algorithm does not support a feature of a model
biosimulators_utils.simulator.exec module¶
Utilities for executing command-line interfaces to simulators and containers that contain command-line interfaces to simulators
- Author
Jonathan Karr <karr@mssm.edu>
- Date
2020-12-06
- Copyright
2020, Center for Reproducible Biomedical Modeling
- License
MIT
- biosimulators_utils.simulator.exec.exec_sedml_docs_in_archive_with_containerized_simulator(archive_filename, out_dir, docker_image, docker_image_temp_dir='/tmp', docker_image_path_sep='/', environment=None, pull_docker_image=True, user_to_exec_within_container='_CURRENT_USER_', allocate_tty=True, remove_docker_container=True)[source]¶
Use a containerized simulator tool to execute the tasks specified in a COMBINE/OMEX archive and generate the reports specified in the archive
- Parameters
archive_filename (
str
) – path to a COMBINE/OMEX archiveout_dir (
str
) – directory where outputs should be saveddocker_image (
str
) – tag (e.g.,biosimulators/tellurium
) or URL (ghcr.io/biosimulators/tellurium
) for a Docker image of a simulatordocker_image_temp_dir (
str
, optional) – Path to the temporary directory within the Docker image (e.g.,/tmp
for Linux images,C:\Users\{ user }\AppData\Local\Temp
for Windows images). The path can either be an absolute path or a path relative to the working directory of the image.docker_image_path_sep (
str
, optional) – Path separator for the image (e.g.,/
for Linux, Mac OS, Unix images;\
for Windows images)environment (
dict
, optional) – environment variables for executing the Docker imagepull_docker_image (
bool
, optional) – ifTrue
, pull the Docker image (if the image isn’t available locally, this will cause the image to be downloaded; this will cause the image to be updated)user_to_exec_within_container (
str
, optional) –username or user id to execute commands within the Docker container
Use
_CURRENT_USER_
to indicate that the Docker container should execute commands as the current user (os.getuid()
)Use the format
<name|uid>[:<group|gid>]
to indicate any other user/group that the Docker container should use to execute commands
allocate_tty (
bool
, optional) – ifTrue
, allocate a pseudo-TTYremove_docker_container (
bool
, optional) – ifTrue
, automatically remove the container when it exits
- Raises
RuntimeError – if the execution failed
- biosimulators_utils.simulator.exec.exec_sedml_docs_in_archive_with_simulator_cli(archive_filename, out_dir, simulator_command, environment=None)[source]¶
Use a command-line interface to a simulation tool to execute the tasks specified in archive COMBINE/OMEX archive and generate the reports specified in the archive
- Parameters
archive_filename (
str
) – path to a COMBINE/OMEX archiveout_dir (
str
) – directory where outputs should be savedsimulator_command (
str
) – system command for the simulator to executeenvironment (
dict
, optional) – environment variables for executing the Docker image
- Raises
RuntimeError – if the execution failed
biosimulators_utils.simulator.io module¶
Methods for reading specifications of simulators
- Author
Jonathan Karr <karr@mssm.edu>
- Date
2020-12-06
- Copyright
2020, Center for Reproducible Biomedical Modeling
- License
MIT
- biosimulators_utils.simulator.io.read_simulator_specs(path_or_url, patch=None, validate=True)[source]¶
Read the specifications of a simulator
- Parameters
path_or_url (
str
) – file path or URL for the specifications of a simulatorpatch (
dict
, optional) – values of properties to supersede those inpath_or_url
validate (
bool
, optional) – whether to validate the specifications
- Returns
specifications of a simulator
- Return type
dict
- Raises
requests.RequestException – if the specifications could not be retrieved
simplejson.errors.JSONDecodeError – if the specifications are not propertly encoded into JSON
ValueError – if the specifications are not consistent with the BioSimulators schema
biosimulators_utils.simulator.specs module¶
Utilities for reading the specifications of a simulator
- Author
Jonathan Karr <karr@mssm.edu>
- Date
2020-12-06
- Copyright
2020, Center for Reproducible Biomedical Modeling
- License
MIT
- biosimulators_utils.simulator.specs.does_algorithm_implementation_have_capabilities_to_execute_parameter(parameter_kisao_id, algorithm_specs)[source]¶
Determine if an implementation of an algorithm has the capabilities to execute a model langugae
- Parameters
parameter_kisao_id (
str
) – KiSAO id for an algorithm parameteralgorithm_specs (
dict
with schemahttps://api.biosimulators.org/openapi.json#/components/schemas/Algorithm
) – specifications of the implementation of an algorithm
- Returns
whether the implementation of the algorithm has the capabilities to execute the SED parameter
- Return type
bool
- biosimulators_utils.simulator.specs.does_algorithm_implementation_have_capabilities_to_execute_sed_model_language(model_language, algorithm_specs)[source]¶
Determine if an implementation of an algorithm has the capabilities to execute a model langugae
- Parameters
model_language (
str
) – SED URN for model languagealgorithm_specs (
dict
with schemahttps://api.biosimulators.org/openapi.json#/components/schemas/Algorithm
) – specifications of the implementation of an algorithm
- Returns
whether the implementation of the algorithm has the capabilities to execute the SED model language
- Return type
bool
- biosimulators_utils.simulator.specs.does_algorithm_implementation_have_capabilities_to_execute_sed_task(task, algorithm_specs, alg_substitution_policy=AlgorithmSubstitutionPolicy.SAME_VARIABLES)[source]¶
Determine if an implementation of an algorithm has the capabilities to execute a SED task
- Parameters
task (
Task
) – SED taskalgorithm_specs (
dict
with schemahttps://api.biosimulators.org/openapi.json#/components/schemas/Algorithm
) – specifications of the implementation of an algorithmalg_substitution_policy (
AlgorithmSubstitutionPolicy
, optional) – algorithm substitution policy
- Returns
whether the implementation of the algorithm has the capabilities to execute the SED task
- Return type
bool
- biosimulators_utils.simulator.specs.does_simulator_have_capabilities_to_execute_sed_document(sed_doc, simulator_specs, alg_substitution_policy=AlgorithmSubstitutionPolicy.SAME_VARIABLES)[source]¶
Determine if a simulator has the capabilities to execute a SED document
- Parameters
sed_doc (
SedDocument
) – SED documentsimulator_specs (
dict
with schemahttps://api.biosimulators.org/openapi.json#/components/schemas/Simulator
) – specifications of a simulation toolalg_substitution_policy (
AlgorithmSubstitutionPolicy
, optional) – algorithm substitution policy
- Returns
whether the simulator has the capabilities to execute the SED document
- Return type
bool
- biosimulators_utils.simulator.specs.does_simulator_have_capabilities_to_execute_sed_task(task, simulator_specs, alg_substitution_policy=AlgorithmSubstitutionPolicy.SAME_VARIABLES)[source]¶
Determine if a simulator has the capabilities to execute a SED task
- Parameters
task (
Task
) – SED tasksimulator_specs (
dict
with schemahttps://api.biosimulators.org/openapi.json#/components/schemas/Simulator
) – specifications of a simulation toolalg_substitution_policy (
AlgorithmSubstitutionPolicy
, optional) – algorithm substitution policy
- Returns
whether the simulator has the capabilities to execute the SED task
- Return type
bool
- biosimulators_utils.simulator.specs.gen_algorithms_from_specs(specifications)[source]¶
Generate a list of algorithms and their parameters from the specifications of a simulator
- Parameters
specifications (
dict
orstr
) – specifications or path to specifications- Returns
dictionary that maps KiSAO ids to algorithms and their parameters
- Return type
dict
ofstr
toAlgorithm
- biosimulators_utils.simulator.specs.get_simulator_specs(id, version='latest')[source]¶
Get the specifications of a simulation tool from the BioSimulators registry
- Parameters
id (
str
) – idversion (
str
, optional) – version
- Returns
specifications
- Return type
dict
with schemahttps://api.biosimulators.org/openapi.json#/components/schemas/Simulator
biosimulators_utils.simulator.utils module¶
Utilities for simulators
- Author
Jonathan Karr <karr@mssm.edu>
- Date
2020-12-30
- Copyright
2020, Center for Reproducible Biomedical Modeling
- License
MIT
- biosimulators_utils.simulator.utils.get_algorithm_substitution_policy(config=None)[source]¶
Get the current algorithm substitution policy based on the value of the
ALGORITHM_SUBSTITUTION_POLICY
environment variable.- Parameters
config (
Config
, optional) – config- Returns
policy
- Return type
AlgorithmSubstitutionPolicy
- Raises
ValueError – if the value of
ALGORITHM_SUBSTITUTION_POLICY
is not the name of a recognized policy