Modeling

Modeling module (`mira.modeling`)

Modeling module for MIRA.

The top level contains the Model class, toghether with the Variable, Transition, and ModelParameter classes, used to represent a Model.

class Model(template_model)[source]

Bases: object

A model representation generated from a template model.

template_model

The template model used to generate the model

Type:: TemplateModel

variables

A dictionary mapping from variable keys to variables

Type:: dict[Hashable, Variable]

parameters

A dictionary mapping from parameter keys to parameters

Type:: dict[Hashable, ModelParameter]

transitions

A dictionary mapping from transition keys to transitions

Type:: dict[Hashable, Transition]

observables

A dictionary mapping from observable keys to observables

Type:: dict[Hashable, ModelObservable]

Parameters:: template_model (TemplateModel) – A template model to generate a model from

assemble_variable(concept, initials=None)[source]

Assemble a variable from a concept and optional dictionary of initial values.

Parameters:

concept (Concept) – The concept for the variable
initials (Optional[Mapping[str, Initial]]) – A dictionary mapping from names of concepts to objects representing their initial values

Return type:

Variable

Returns:

A variable object, representing a concept and its initial value

assemble_parameter(template, tkey)[source]

Assemble a parameter from a template and a transition key.

Parameters:

template (Template) – The template to assemble a parameter from
tkey (tuple[str, ...]) – The transition key to assemble a parameter from

Return type:

ModelParameter

Returns:

A model parameter

make_model()[source]: Initialize the model

class Transition(key, consumed, produced, control, rate, template_type, template)[source]

Bases: object

A transition between two concepts, with a rate law.

key

A tuple of the form (consumed, produced, control, rate)

Type:: tuple[str]

consumed

The variables consumed by the transition

Type:: tuple[Variable]

produced

The variables produced by the transition

Type:: tuple[Variable]

control

The variables that control the transition

Type:: tuple[Variable]

class Variable(key, data, concept)[source]

Bases: object

A variable representation of a concept in Model

key

A tuple of strings representing the concept name, grounding, and context

Type:: tuple[str, …]

data

A dictionary of data about the variable

Type:: dict

concept

The concept associated with the variable

Type:: Concept

class ModelParameter(key, display_name=None, description=None, value=None, distribution=None, placeholder=None, concept=None)[source]

Bases: object

A parameter for a model.

key

A tuple of strings representing the transition key and the parameter type

Type:: tuple[str, …]

display_name

The display name of the parameter. (optional)

Type:: str

description

A description of the parameter. (optional)

Type:: str

value

The value of the parameter. (optional)

Type:: float

distribution

The distribution of the parameter. (optional)

Type:: str

placeholder

Whether the parameter is a placeholder. (optional)

Type:: bool

concept

The concept associated with the parameter. (optional)

Type:: Concept

ASKEM AMR Petri net generation (`mira.modeling.amr.petrinet`)

This module implements generation into Petri net models which are defined at https://github.com/DARPA-ASKEM/Model-Representations/tree/main/petrinet.

class AMRPetriNetModel(model)[source]

Bases: object

A class representing a PetriNet model.

Instantiate a petri net model from a generic transition model.

Parameters:: model (Model) – The pre-compiled transition model

to_json(name=None, description=None, model_version=None)[source]

Return a JSON dict structure of the Petri net model.

Parameters:

name (str) – The name of the model. Defaults to the name of the original template model that produced the input Model instance or, if not available, ‘Model’.
description (str) – A description of the model. Defaults to the description of the original template model that produced the input Model instance or, if not available, the name of the model.
model_version (str) – The version of the model. Defaults to ‘0.1’.

Returns:

A JSON dict representing the Petri net model.

Return type:

JSON

to_pydantic(name=None, description=None, model_version=None)[source]

Return a Pydantic model representation of the Petri net model.

Parameters:

name – The name of the model. Defaults to the name of the original template model that produced the input Model instance or, if not available, ‘Model’.
description – A description of the model. Defaults to the description of the original template model that produced the input Model instance or, if not available, the name of the model.
model_version – The version of the model. Defaults to ‘0.1’.

Return type:

ModelSpecification

Returns:

A Pydantic model representation of the Petri net model.

to_json_str(**kwargs)[source]

Return a JSON string representation of the Petri net model.

Parameters:: kwargs – Additional keyword arguments to pass to json.dumps().
Return type:: str
Returns:: A JSON string representation of the Petri net model.

to_json_file(fname, name=None, description=None, model_version=None, **kwargs)[source]

Write the Petri net model to a JSON file

Parameters:

fname (str) – The file name to write to.
name (str, optional) – The name of the model.
description (str, optional) – A description of the model.
model_version (str, optional) – The version of the model.
kwargs – Additional keyword arguments to pass to json.dump().

pydantic model ModelSpecification[source]

Bases: BaseModel

A Pydantic model corresponding to the PetriNet JSON schema.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema

{
   "title": "ModelSpecification",
   "description": "A Pydantic model corresponding to the PetriNet JSON schema.",
   "type": "object",
   "properties": {
      "header": {
         "$ref": "#/definitions/Header"
      },
      "properties": {
         "title": "Properties",
         "type": "object"
      },
      "model": {
         "$ref": "#/definitions/PetriModel"
      },
      "semantics": {
         "$ref": "#/definitions/Ode"
      },
      "metadata": {
         "title": "Metadata",
         "type": "object"
      }
   },
   "required": [
      "header",
      "model"
   ],
   "definitions": {
      "Header": {
         "title": "Header",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "schema": {
               "title": "Schema",
               "type": "string"
            },
            "schema_name": {
               "title": "Schema Name",
               "type": "string"
            },
            "description": {
               "title": "Description",
               "type": "string"
            },
            "model_version": {
               "title": "Model Version",
               "type": "string"
            }
         },
         "required": [
            "name",
            "schema",
            "schema_name",
            "description",
            "model_version"
         ]
      },
      "Units": {
         "title": "Units",
         "type": "object",
         "properties": {
            "expression": {
               "title": "Expression",
               "type": "string"
            },
            "expression_mathml": {
               "title": "Expression Mathml",
               "type": "string"
            }
         },
         "required": [
            "expression",
            "expression_mathml"
         ]
      },
      "State": {
         "title": "State",
         "type": "object",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "name": {
               "title": "Name",
               "type": "string"
            },
            "grounding": {
               "title": "Grounding",
               "type": "object"
            },
            "units": {
               "$ref": "#/definitions/Units"
            }
         },
         "required": [
            "id"
         ]
      },
      "TransitionProperties": {
         "title": "TransitionProperties",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "grounding": {
               "title": "Grounding",
               "type": "object"
            }
         }
      },
      "Transition": {
         "title": "Transition",
         "type": "object",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "input": {
               "title": "Input",
               "type": "array",
               "items": {
                  "type": "string"
               }
            },
            "output": {
               "title": "Output",
               "type": "array",
               "items": {
                  "type": "string"
               }
            },
            "grounding": {
               "title": "Grounding",
               "type": "object"
            },
            "properties": {
               "$ref": "#/definitions/TransitionProperties"
            }
         },
         "required": [
            "id",
            "input",
            "output"
         ]
      },
      "PetriModel": {
         "title": "PetriModel",
         "type": "object",
         "properties": {
            "states": {
               "title": "States",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/State"
               }
            },
            "transitions": {
               "title": "Transitions",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Transition"
               }
            }
         },
         "required": [
            "states",
            "transitions"
         ]
      },
      "Rate": {
         "title": "Rate",
         "type": "object",
         "properties": {
            "target": {
               "title": "Target",
               "type": "string"
            },
            "expression": {
               "title": "Expression",
               "type": "string"
            },
            "expression_mathml": {
               "title": "Expression Mathml",
               "type": "string"
            }
         },
         "required": [
            "target",
            "expression",
            "expression_mathml"
         ]
      },
      "Initial": {
         "title": "Initial",
         "type": "object",
         "properties": {
            "target": {
               "title": "Target",
               "type": "string"
            },
            "expression": {
               "title": "Expression",
               "type": "string"
            },
            "expression_mathml": {
               "title": "Expression Mathml",
               "type": "string"
            }
         },
         "required": [
            "target",
            "expression",
            "expression_mathml"
         ]
      },
      "Distribution": {
         "title": "Distribution",
         "type": "object",
         "properties": {
            "type": {
               "title": "Type",
               "type": "string"
            },
            "parameters": {
               "title": "Parameters",
               "type": "object"
            }
         },
         "required": [
            "type",
            "parameters"
         ]
      },
      "Parameter": {
         "title": "Parameter",
         "type": "object",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "description": {
               "title": "Description",
               "type": "string"
            },
            "value": {
               "title": "Value",
               "type": "number"
            },
            "grounding": {
               "title": "Grounding",
               "type": "object"
            },
            "distribution": {
               "$ref": "#/definitions/Distribution"
            },
            "units": {
               "$ref": "#/definitions/Units"
            }
         },
         "required": [
            "id"
         ]
      },
      "Time": {
         "title": "Time",
         "type": "object",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "units": {
               "$ref": "#/definitions/Units"
            }
         },
         "required": [
            "id"
         ]
      },
      "Observable": {
         "title": "Observable",
         "type": "object",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "name": {
               "title": "Name",
               "type": "string"
            },
            "grounding": {
               "title": "Grounding",
               "type": "object"
            },
            "expression": {
               "title": "Expression",
               "type": "string"
            },
            "expression_mathml": {
               "title": "Expression Mathml",
               "type": "string"
            }
         },
         "required": [
            "id",
            "expression",
            "expression_mathml"
         ]
      },
      "OdeSemantics": {
         "title": "OdeSemantics",
         "type": "object",
         "properties": {
            "rates": {
               "title": "Rates",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Rate"
               }
            },
            "initials": {
               "title": "Initials",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Initial"
               }
            },
            "parameters": {
               "title": "Parameters",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Parameter"
               }
            },
            "time": {
               "$ref": "#/definitions/Time"
            },
            "observables": {
               "title": "Observables",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Observable"
               }
            }
         },
         "required": [
            "rates",
            "initials",
            "parameters",
            "observables"
         ]
      },
      "Ode": {
         "title": "Ode",
         "type": "object",
         "properties": {
            "ode": {
               "$ref": "#/definitions/OdeSemantics"
            }
         }
      }
   }
}

Fields:

header (mira.modeling.amr.petrinet.Header)
metadata (Dict | None)
model (mira.modeling.amr.petrinet.PetriModel)
properties (Dict | None)
semantics (mira.modeling.amr.petrinet.Ode | None)

field header: Header [Required]

field metadata: Optional[Dict] = None

field model: PetriModel [Required]

field properties: Optional[Dict] = None

field semantics: Optional[Ode] = None

template_model_to_petrinet_json(tm)[source]

Convert a template model to a PetriNet JSON dict.

Parameters:: tm (TemplateModel) – The template model to convert.
Return type:: A JSON dict representing the PetriNet model.

ASKEM AMR Stockflow generation (`mira.modeling.amr.stockflow`)

This module implements parsing Stock and Flow models defined in https://github.com/DARPA-ASKEM/Model-Representations/tree/main/stockflow.

class AMRStockFlowModel(model)[source]

Bases: object

A class representing a Stock and Flow Model

Instantiate a stock and flow model from a generic transition model.

Parameters:: model (Model) – The pre-compiled transition model

to_json()[source]: Return a JSON dict structure of the Stock and Flow model.

template_model_to_stockflow_json(tm)[source]

Convert a template model to a Stock and Flow JSON dict.

Parameters:: tm (TemplateModel) – The template model to convert.
Returns:: A JSON dict representing the Stock and Flow model.
Return type:: JSON

ASKEM AMR operations (`mira.modeling.amr.ops`)

This module contains functions for editing ASKEM Model Representation models

replace_state_id(model, old_id, new_id)[source]

Replace the ID of a state.

Parameters:

model (JSON) – The model as an AMR JSON
old_id (str) – The ID of the state to replace
new_id (str) – The new ID to replace the old ID with

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_transition_id(model, old_id, new_id)[source]

Replace the ID of a transition.

Parameters:

model (JSON) – The model as an AMR JSON
old_id – The ID of the transition to replace
new_id – The new ID to replace the old ID with

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_observable_id(model, old_id, new_id, name=None)[source]

Replace the ID and display name (optional) of an observable.

Parameters:

model (JSON) – The model as an AMR JSON
old_id (str) – The ID of the observable to replace
new_id (str) – The new ID to replace the old ID with
name (str) – The new display name to replace the old display name with (optional)

Returns:

The updated model as an AMR JSON

Return type:

JSON

remove_observable(model, removed_id)[source]

Remove an observable from the template model

Parameters:

model (JSON) – The model as an AMR JSON
removed_id (str) – The ID of the observable to remove

Returns:

The updated model as an AMR JSON

Return type:

JSON

remove_parameter(model, removed_id, replacement_value=None)[source]

Substitute every instance of the parameter with the given replacement_value. If replacement_value is none, substitute the parameter with 0.

Parameters:

model (JSON) – The model as an AMR JSON
removed_id (str) – The ID of the parameter to remove
replacement_value – The value to replace the parameter with (optional)

Returns:

The updated model as an AMR JSON

Return type:

JSON

add_observable(model, new_id, new_name, new_expression)[source]

Add a new observable object to the template model

Parameters:

model (JSON) – The model as an AMR JSON
new_id (str) – The ID of the new observable to add
new_name (str) – The display name of the new observable to add
new_expression (str) – The expression of the new observable to add as a MathML XML string

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_parameter_id(model, old_id, new_id)[source]

Replace the ID of a parameter

Parameters:

model (JSON) – The model as an AMR JSON
old_id (str) – The ID of the parameter to replace
new_id (str) – The new ID to replace the old ID with

Returns:

The updated model as an AMR JSON

Return type:

JSON

add_parameter(model, parameter_id, name=None, description=None, value=None, distribution=None, units_mathml=None)[source]

Add a new parameter to the template model

Parameters:

model (JSON) – The model as an AMR JSON
parameter_id (str) – The ID of the new parameter to add
name (str) – The display name of the new parameter (optional)
description (str) – The description of the new parameter (optional)
value (float) – The value of the new parameter (optional)
distribution (Distribution) – The distribution of the new parameter (optional)
units_mathml (str) – The units of the new parameter as a MathML XML string (optional)

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_initial_id(model, old_id, new_id)[source]

Replace the ID of an initial.

Parameters:

model (JSON) – The model as an AMR JSON
old_id (str) – The ID of the initial to replace
new_id (str) – The new ID to replace the old ID with

Returns:

The updated model as an AMR JSON

Return type:

JSON

remove_state(model, state_id)[source]

Remove a state from the template model

Parameters:

model (JSON) – The model as an AMR JSON
state_id (str) – The ID of the state to remove

Returns:

The updated model as an AMR JSON

Return type:

JSON

add_state(model, state_id, name=None, units_mathml=None, grounding=None, context=None)[source]

Add a new state to the template model

Parameters:

model (JSON) – The model as an AMR JSON
state_id (str) – The ID of the new state to add
name (str) – The display name of the new state (optional)
units_mathml (str) – The units of the new state as a MathML XML string (optional)
grounding (Mapping[str, str]) – The grounding of the new state (optional)
context (Mapping[str, str]) – The context of the new state (optional)

Returns:

The updated model as an AMR JSON

Return type:

JSON

remove_transition(model, transition_id)[source]

Remove a transition object from the template model

Parameters:

model (JSON) – The model as an AMR JSON
transition_id (str) – The ID of the transition to remove

Returns:

The updated model as an AMR JSON

Return type:

JSON

add_transition(model, new_transition_id, src_id=None, tgt_id=None, rate_law_mathml=None, params_dict=None)[source]

Add a new transition to a model

Parameters:

model (JSON) – The model as an AMR JSON
new_transition_id (str) – The ID of the new transition to add
src_id (str) – The ID of the subject of the newly created transition (default None)
tgt_id (str) – The ID of the outcome of the newly created transition (default None)
rate_law_mathml (str) – The rate law associated with the newly created transition
params_dict (Mapping) – A mapping of parameter attributes to their respective values if the user decides to explicitly create parameters

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_rate_law_sympy(model, transition_id, new_rate_law)[source]

Replace the rate law of transition. The new rate law passed in will be a sympy.Expr object

Parameters:

model – The model as an AMR JSON
transition_id (str) – The ID of the transition whose rate law is to be replaced, this is typically the name of the transition
new_rate_law (Expr) – The new rate law to replace the existing rate law with

Returns:

The updated model as an AMR JSON

replace_rate_law_mathml(model, transition_id, new_rate_law)[source]

Replace the rate law of a transition.

Parameters:

model (JSON) – The model as an AMR JSON
transition_id (str) – The ID of the transition whose rate law is to be replaced, this is typically the name of the transition
new_rate_law (str) – The new rate law to replace the existing rate law with as a MathML XML string

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_observable_expression_sympy(model, obs_id, new_expression_sympy)[source]

Replace the expression of an observable

Parameters:

model (JSON) – The model as an AMR JSON
obs_id (str) – The ID of the observable to replace the expression of
new_expression_sympy (Expr) – The new expression to replace the existing expression with as a sympy.Expr object

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_initial_expression_sympy(model, initial_id, new_expression_sympy)[source]

Replace the expression of an initial.

Parameters:

model (JSON) – The model as an AMR JSON
initial_id (str) – The ID of the initial to replace the expression of
new_expression_sympy (Expr) – The new expression to replace the existing expression with as a sympy.Expr object

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_observable_expression_mathml(amr, obs_id, new_expression_mathml)[source]

Replace the expression of an observable.

Parameters:

amr (JSON) – The model as an AMR JSON
obs_id (str) – The ID of the observable to replace the expression of
new_expression_mathml (str) – The new expression to replace the existing expression with as a MathML XML string

Returns:

The updated model as an AMR JSON

Return type:

JSON

replace_initial_expression_mathml(amr, initial_id, new_expression_mathml)[source]

Replace the expression of an initial.

Parameters:

amr (JSON) – The model as an AMR JSON
initial_id (str) – The ID of the initial to replace the expression of
new_expression_mathml (str) – The new expression to replace the existing expression with as a MathML XML string

Returns:

The updated model as an AMR JSON

Return type:

JSON

stratify(*args, **kwargs)[source]

Multiplies a model into several strata.

E.g., can turn the SIR model into a two-city SIR model by splitting each concept into two derived concepts, each with the context for one of the two cities

Parameters:

model – An AMR model JSON
key – The (singular) name of the stratification, e.g., "city"
strata – A list of the values for stratification, e.g., ["boston", "nyc"] or [geonames:4930956, geonames:5128581].
strata_curie_to_name – If provided, should map from a key used in strata to a name. For example, {"geonames:4930956": "boston", "geonames:5128581": "nyc"}.
strata_name_lookup – If true, will try to look up the entity names of the strata values under the assumption that they are curies. This flag has no impact if strata_curie_to_name is given.
structure – An iterable of pairs corresponding to a directed network structure where each of the pairs has two strata. If none given, will assume a complete network structure. If no structure is necessary, pass an empty list.
directed – Should the reverse direction conversions be added based on the given structure?
conversion_cls – The template class to be used for conversions between strata defined by the network structure. Defaults to NaturalConversion
cartesian_control –
If true, splits all control relationships based on the stratification.

This should be true for an SIR epidemiology model, the susceptibility to infected transition is controlled by infected. If the model is stratified by vaccinated and unvaccinated, then the transition from vaccinated susceptible population to vaccinated infected populations should be controlled by both infected vaccinated and infected unvaccinated populations.

This should be false for stratification of an SIR epidemiology model based on cities, since the infected population in one city won’t (directly, through the perspective of the model) affect the infection of susceptible population in another city.
modify_names – If true, will modify the names of the concepts to include the strata (e.g., "S" becomes "S_boston"). If false, will keep the original names.
params_to_stratify – A list of parameters to stratify. If none given, will stratify all parameters.
params_to_preserve – A list of parameters to preserve. If none given, will stratify all parameters.
concepts_to_stratify – A list of concepts to stratify. If none given, will stratify all concepts.
concepts_to_preserve – A list of concepts to preserve. If none given, will stratify all concepts.

Returns:

A stratified AMR model JSON

simplify_rate_laws(*args, **kwargs)[source]

Return an AMR model JSON after rewriting templates by simplifying rate laws.

Parameters:: model – An AMR model JSON
Returns:: An AMR model JSON with simplified rate laws.

aggregate_parameters(*args, **kwargs)[source]

Return an AMR model JSON after aggregating parameters for mass-action rate laws.

Parameters:: model – An AMR model JSON whose rate laws will be aggregated.
Returns:: An AMR model JSON with aggregated parameters.

counts_to_dimensionless(*args, **kwargs)[source]

Convert all quantities using a given counts unit to dimensionless units.

Parameters:

model – An AMR model JSON.
counts_unit – The unit of the counts.
norm_factor – The normalization factor to convert counts to dimensionsionless.

Returns:

An AMR model JSON with all entity concentrations converted to dimensionless units.

ASKEM AMR Regulatory net generation (`mira.modeling.amr.regnet`)

This module implements generation into Petri net models which are defined at https://github.com/DARPA-ASKEM/Model-Representations/tree/main/regnet.

class AMRRegNetModel(model)[source]

Bases: object

A class representing a PetriNet model.

Instantiate a regnet model from a generic transition model.

Parameters:: model (Model) – The pre-compiled transition model

create_edge(transition, source, target, edge_id, duplicate)[source]

Create and append a transition dictionary to the list of transitions

Parameters:

transition (Transition) – The Transition object
source (str) – The name of the source of the transition
target (str) – The name of the target of the transition
edge_id (int) – The id to assign to the transition
duplicate (bool) – A boolean that tells us whether the transition we are processing has already been processed at least once. This is for the purpose of not adding duplicate rate laws to the output amr.

to_json(name=None, description=None, model_version=None)[source]

Return a JSON dict structure of the Petri net model.

Parameters:

name (str) – The name of the model. Defaults to the model name of the original template model of the input Model instance, or “Model” if no name is available.
description (str) – The description of the model. Defaults to the description of the original template model of the input Model instance, or the model name if no description is available.
model_version (str) – The version of the model. Defaults to 0.1

Returns:

A JSON representation of the Petri net model.

Return type:

JSON

to_pydantic(name=None, description=None, model_version=None)[source]

Return a Pydantic model specification of the Petri net model.

Parameters:

name (str) – The name of the model. Defaults to the model name of the original template model of the input Model instance, or “Model” if no name is available.
description (str) – The description of the model. Defaults to the description of the original template model of the input Model instance, or the model name if no description is available.
model_version (str) – The version of the model. Defaults to 0.1

Return type:

ModelSpecification

Returns:

A Pydantic model specification of the Petri net model.

to_json_str(**kwargs)[source]

Return a JSON string representation of the Petri net model.

Parameters:: **kwargs – Keyword arguments to be passed to json.dumps
Returns:: A JSON string representation of the Petri net model.

to_json_file(fname, name=None, description=None, model_version=None, **kwargs)[source]

Write the Petri net model to a JSON file.

Parameters:

fname (str) – The file name to write to.
name (str) – The name of the model. Defaults to the model name of the original template model of the input Model instance, or “Model” if no name is available.
description (str) – The description of the model. Defaults to the description of the original template model of the input Model instance, or the model name if no description is available.
model_version (str) – The version of the model. Defaults to 0.1
**kwargs – Keyword arguments to be passed to json.dump

pydantic model ModelSpecification[source]

Bases: BaseModel

A Pydantic model specification of the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Show JSON schema

{
   "title": "ModelSpecification",
   "description": "A Pydantic model specification of the model.",
   "type": "object",
   "properties": {
      "header": {
         "$ref": "#/definitions/Header"
      },
      "properties": {
         "title": "Properties",
         "type": "object"
      },
      "model": {
         "$ref": "#/definitions/RegNetModel"
      },
      "semantics": {
         "$ref": "#/definitions/Ode"
      },
      "metadata": {
         "title": "Metadata",
         "type": "object"
      }
   },
   "required": [
      "header",
      "model"
   ],
   "definitions": {
      "Header": {
         "title": "Header",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "schema_name": {
               "title": "Schema Name",
               "type": "string"
            },
            "schema": {
               "title": "Schema",
               "type": "string"
            },
            "description": {
               "title": "Description",
               "type": "string"
            },
            "model_version": {
               "title": "Model Version",
               "type": "string"
            }
         },
         "required": [
            "name",
            "schema_name",
            "schema",
            "description",
            "model_version"
         ]
      },
      "Initial": {
         "title": "Initial",
         "type": "object",
         "properties": {
            "expression": {
               "title": "Expression",
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "number"
                  }
               ]
            },
            "expression_mathml": {
               "title": "Expression Mathml",
               "type": "string"
            }
         },
         "required": [
            "expression",
            "expression_mathml"
         ]
      },
      "State": {
         "title": "State",
         "type": "object",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "name": {
               "title": "Name",
               "type": "string"
            },
            "initial": {
               "$ref": "#/definitions/Initial"
            }
         },
         "required": [
            "id",
            "name"
         ]
      },
      "TransitionProperties": {
         "title": "TransitionProperties",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "grounding": {
               "title": "Grounding",
               "type": "object"
            },
            "rate": {
               "title": "Rate",
               "type": "object"
            }
         }
      },
      "Transition": {
         "title": "Transition",
         "type": "object",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "input": {
               "title": "Input",
               "type": "array",
               "items": {
                  "type": "string"
               }
            },
            "output": {
               "title": "Output",
               "type": "array",
               "items": {
                  "type": "string"
               }
            },
            "properties": {
               "$ref": "#/definitions/TransitionProperties"
            }
         },
         "required": [
            "id",
            "input",
            "output"
         ]
      },
      "Distribution": {
         "title": "Distribution",
         "type": "object",
         "properties": {
            "type": {
               "title": "Type",
               "type": "string"
            },
            "parameters": {
               "title": "Parameters",
               "type": "object"
            }
         },
         "required": [
            "type",
            "parameters"
         ]
      },
      "Parameter": {
         "title": "Parameter",
         "type": "object",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "value": {
               "title": "Value",
               "type": "number"
            },
            "description": {
               "title": "Description",
               "type": "string"
            },
            "distribution": {
               "$ref": "#/definitions/Distribution"
            }
         },
         "required": [
            "id"
         ]
      },
      "RegNetModel": {
         "title": "RegNetModel",
         "type": "object",
         "properties": {
            "vertices": {
               "title": "Vertices",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/State"
               }
            },
            "edges": {
               "title": "Edges",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Transition"
               }
            },
            "parameters": {
               "title": "Parameters",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Parameter"
               }
            }
         },
         "required": [
            "vertices",
            "edges",
            "parameters"
         ]
      },
      "Rate": {
         "title": "Rate",
         "type": "object",
         "properties": {
            "expression": {
               "title": "Expression",
               "type": "string"
            },
            "expression_mathml": {
               "title": "Expression Mathml",
               "type": "string"
            }
         },
         "required": [
            "expression",
            "expression_mathml"
         ]
      },
      "Unit": {
         "title": "Unit",
         "description": "A unit of measurement.",
         "type": "object",
         "properties": {
            "expression": {
               "title": "Expression",
               "description": "The expression for the unit.",
               "type": "string",
               "example": "2*x"
            }
         },
         "required": [
            "expression"
         ]
      },
      "Time": {
         "title": "Time",
         "description": "A special type of Concept that represents time.",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "description": "The symbol of the time variable in the model.",
               "default": "t",
               "type": "string"
            },
            "units": {
               "title": "Units",
               "description": "The units of the time variable.",
               "allOf": [
                  {
                     "$ref": "#/definitions/Unit"
                  }
               ]
            }
         }
      },
      "Observable": {
         "title": "Observable",
         "description": "An observable is a special type of Concept that carries an expression.\n\nObservables are used to define the readouts of a model, useful when a\nreadout is not defined as a state variable but is rather a function of\nstate variables.",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "description": "The name of the concept.",
               "type": "string"
            },
            "display_name": {
               "title": "Display Name",
               "description": "An optional display name for the concept. If not provided, the name can be used for display purposes.",
               "type": "string"
            },
            "description": {
               "title": "Description",
               "description": "An optional description of the concept.",
               "type": "string"
            },
            "identifiers": {
               "title": "Identifiers",
               "description": "A mapping of namespaces to identifiers.",
               "type": "object",
               "additionalProperties": {
                  "type": "string"
               }
            },
            "context": {
               "title": "Context",
               "description": "A mapping of context keys to values.",
               "type": "object",
               "additionalProperties": {
                  "type": "string"
               }
            },
            "units": {
               "title": "Units",
               "description": "The units of the concept.",
               "allOf": [
                  {
                     "$ref": "#/definitions/Unit"
                  }
               ]
            },
            "expression": {
               "title": "Expression",
               "description": "The expression for the observable.",
               "type": "string",
               "example": "2*x"
            }
         },
         "required": [
            "name",
            "expression"
         ]
      },
      "OdeSemantics": {
         "title": "OdeSemantics",
         "type": "object",
         "properties": {
            "rates": {
               "title": "Rates",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Rate"
               }
            },
            "time": {
               "$ref": "#/definitions/Time"
            },
            "observables": {
               "title": "Observables",
               "type": "array",
               "items": {
                  "$ref": "#/definitions/Observable"
               }
            }
         },
         "required": [
            "rates",
            "observables"
         ]
      },
      "Ode": {
         "title": "Ode",
         "type": "object",
         "properties": {
            "ode": {
               "$ref": "#/definitions/OdeSemantics"
            }
         }
      }
   }
}

Fields:

header (mira.modeling.amr.regnet.Header)
metadata (Dict | None)
model (mira.modeling.amr.regnet.RegNetModel)
properties (Dict | None)
semantics (mira.modeling.amr.regnet.Ode | None)

field header: Header [Required]

field metadata: Optional[Dict] = None

field model: RegNetModel [Required]

field properties: Optional[Dict] = None

field semantics: Optional[Ode] = None

template_model_to_regnet_json(tm)[source]

Convert a template model to a RegNet JSON dict.

Parameters:: tm (TemplateModel) – The template model to convert.
Return type:: A JSON dict representing the RegNet model.

Model visualization (`mira.modeling.viz`)

Visualization of transition models.

class GraphicalModel(model)[source]

Bases: object

Create a graphical representation of a transition model.

classmethod from_template_model(template_model)[source]

Get a graphical model from a template model.

Return type:: GraphicalModel

write(path, prog='dot', args='', format=None)[source]

Write the graphical representation to a file.

Parameters:

path (Union[str, Path]) – The path to the output file
prog (str) – The graphviz layout program to use, such as “dot”, “neato”, etc.
format (Optional[str]) – Set the file format explicitly
args (str) – Additional arguments to pass to the graphviz bash program

Return type:

None

classmethod for_jupyter(template_model, name='model.png', **kwargs)[source]: Display in jupyter.

ODE model generation and simulation (`mira.modeling.ode`)

class OdeModel(model, initialized)[source]

Bases: object

A class representing an ODE model.

set_parameters(params)[source]: Set the parameters of the model.

get_rhs()[source]: Return the right-hand side of the ODE system.

simulate_ode_model(ode_model, times, initials=None, parameters=None, with_observables=False)[source]

Simulate an ODE model given initial conditions, parameters and a time span.

Parameters:

ode_model (OdeModel) – An ODE model constructed from metamodel templates
initials – A one-dimensional array describing the initial values for the agents in the ODE model
parameters – A dictionary of keys for parameters to their values
times – A one-dimensional array of time values, typically from a linear space like numpy.linspace(0, 25, 100)
with_observables – A boolean indicating whether to return the observables as well as the variables.

Returns:

A two-dimensional array with the first axis being time
and the second axis being the agents in the ODE model.

ACSets Petri net model generation (`mira.modeling.acsets.petri`)

This module implements generation into Petri net models which are defined through a set of states, transitions, and the input and output connections between them.

Once the model is created, it can be exported into JSON following the conventions in https://github.com/AlgebraicJulia/ASKEM-demos/tree/master/data.

class PetriNetModel(model)[source]

Bases: object

A class representing a PetriNet model.

Instantiate a petri net model from a generic transition model.

Parameters:: model (Model) – The pre-compiled transition model

to_json()[source]: Return a JSON dict structure of the Petri net model.

to_json_str()[source]: Return a JSON string representation of the Petri net model.

to_json_file(fname, **kwargs)[source]: Write the Petri net model to a JSON file.

ACSets Stockflow model generation (`mira.modeling.acsets.stockflow`)

This module implements generation into stock and flow models which are defined through a set of stocks, flows, links, and the input and output connections between flows.

class ACSetsStockFlowModel(model)[source]

Bases: object

A class representing a stock and flow model.

Instantiate a stock and flow model from a generic transition model.

Parameters:: model (Model) – The pre-compiled transition model.

to_json()[source]

Return a JSON dict structure of the Petri net model.

Returns:: The JSON dict structure of the stock and flow model.
Return type:: JSON

template_model_to_stockflow_ascet_json(tm)[source]

Convert a TemplateModel into stock flow JSON and return the converted model.

Parameters:: tm (TemplateModel) – The TemplateModel to be converted.
Returns:: The JSON structure representing the stock flow model.
Return type:: JSON

Bilayer model generation (`mira.modeling.bilayer`)

This module can generate a bilayer structure from a MIRA transition model.

class BilayerModel(model)[source]

Bases: object

Class to generate a bilayer model from a transition model.

Parameters:: model (Model) – A MIRA transition model.

static make_bilayer(model)[source]

Generate a bilayer structure and return as a JSON dict.

Parameters:: model (Model) – A MIRA transition model.
Returns:: A JSON dict representing the bilayer structure.
Return type:: JSON

save_bilayer(fname)[source]

Save the generated bilayer into a JSON file.

Parameters:: fname (str) – The file path to save the bilayer to.

Modeling

Modeling module (mira.modeling)

ASKEM AMR Petri net generation (mira.modeling.amr.petrinet)

ASKEM AMR Stockflow generation (mira.modeling.amr.stockflow)

ASKEM AMR operations (mira.modeling.amr.ops)

ASKEM AMR Regulatory net generation (mira.modeling.amr.regnet)

Model visualization (mira.modeling.viz)

ODE model generation and simulation (mira.modeling.ode)

ACSets Petri net model generation (mira.modeling.acsets.petri)

ACSets Stockflow model generation (mira.modeling.acsets.stockflow)

Bilayer model generation (mira.modeling.bilayer)

Modeling module (`mira.modeling`)

ASKEM AMR Petri net generation (`mira.modeling.amr.petrinet`)

ASKEM AMR Stockflow generation (`mira.modeling.amr.stockflow`)

ASKEM AMR operations (`mira.modeling.amr.ops`)

ASKEM AMR Regulatory net generation (`mira.modeling.amr.regnet`)

Model visualization (`mira.modeling.viz`)

ODE model generation and simulation (`mira.modeling.ode`)

ACSets Petri net model generation (`mira.modeling.acsets.petri`)

ACSets Stockflow model generation (`mira.modeling.acsets.stockflow`)

Bilayer model generation (`mira.modeling.bilayer`)