biosimulators_utils.simulator package — BioSimulators utils 0.1.154 documentation

# 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)

  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)

  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)

  Bases: `str`, `enum.Enum`

  Software interface

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

## 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

  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)

  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)

  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, patch=None, validate=True)

  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)

  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)

  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)

  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)

  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)

  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)

  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')

  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)

  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