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 application

  • simulator_name (str) – name of the simulator (e.g., COPASI)

  • simulator_version (str, optional) – version of the simulator

  • simulator_url (str, optional) – URL for information about the simulator

  • combine_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 archive

  • environment_variables (list of EnvironmentVariable, 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

class biosimulators_utils.simulator.data_model.SoftwareInterface(value)[source]#

Bases: str, Enum

Software interface

__format__(format_spec)[source]#

Returns format using actual value type unless __str__ has been overridden.

biosimulators_docker_image = 'BioSimulators Docker image'[source]#
command_line = 'command-line application'[source]#
desktop_application = 'desktop application'[source]#
library = 'library'[source]#
mobile_application = 'mobile application'[source]#
web_application = 'web application'[source]#
web_service = 'web service'[source]#

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: 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 archive

  • out_dir (str) – directory where outputs should be saved

  • docker_image (str) – tag (e.g., biosimulators/tellurium) or URL (ghcr.io/biosimulators/tellurium) for a Docker image of a simulator

  • docker_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 image

  • pull_docker_image (bool, optional) – if True, 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) – if True, allocate a pseudo-TTY

  • remove_docker_container (bool, optional) – if True, 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 archive

  • out_dir (str) – directory where outputs should be saved

  • simulator_command (str) – system command for the simulator to execute

  • environment (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: str, patch: dict | None = None, validate: bool = True)[source]#

Read the specifications of a simulator

Parameters:

  • path_or_url (str) – file path or URL for the specifications of a simulator

  • patch (dict, optional) – values of properties to supersede those in path_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 parameter

  • algorithm_specs (dict with schema https://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 language

  • algorithm_specs (dict with schema https://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 task

  • algorithm_specs (dict with schema https://api.biosimulators.org/openapi.json#/components/schemas/Algorithm) – specifications of the implementation of an algorithm

  • alg_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 document

  • simulator_specs (dict with schema https://api.biosimulators.org/openapi.json#/components/schemas/Simulator) – specifications of a simulation tool

  • alg_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 task

  • simulator_specs (dict with schema https://api.biosimulators.org/openapi.json#/components/schemas/Simulator) – specifications of a simulation tool

  • alg_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 or str) – specifications or path to specifications

Returns:

dictionary that maps KiSAO ids to algorithms and their parameters

Return type:

dict of str to Algorithm

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) – id

  • version (str, optional) – version

Returns:

specifications

Return type:

dict with schema https://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

On this page
Edit on GitHub
Show Source