API :: Formats¶
This page is about importing from and exporting to formats other than
mmt
. If you are interested in the mmt
format, please look at the
section Reading and writing.
One of the main goals of myokit is to provide export of
Simulations to other formats (for example C or matlab). To provide a uniform
interface to these functions the Exporter
class is defined. Import
from other formats is provided through the Importer
interface.
Exporters to exchange or presentation formats will typically export a bare model definition, while exporters to programming languages mostly create a full Simulation including pacing, a simulation engine and even some post processing.
The goal of an Importer
is to produce a (model, protocol, script)
tuple containing the three main parts of an mmt
file. However, most
importers will only provide a model definition so the remaining entries in the
tuple will be None
.
The methods used to import and export programmatically are described below, and and some example code is given.
The following formats are currently supported:
Example¶
To find out which kinds of import/export are available, the methods
exporters()
and importers()
are defined. These
functions return a list of names that can be passed to
exporter()
or importer()
to obtain the class name
of the requested im- or exporter. This is returned as a type
object, from
which instances can then be constructed:
import myokit
from myokit import formats
# Load a (model, protocol, script) tuple
m, p, s = myokit.load('example.mmt')
# Create a simulation
s = myokit.Simulation(m, p)
# Create an Ansi-C exporter
e = formats.exporter('ansic')
# Get some info about this exporter
print e.info()
# Export to the directory /home/michael/test
# If this directory does not exist, the exporter will attempt to create it.
e.export_simulation(s, '/home/michael/test')
Importing¶
-
myokit.formats.
importer
(name)¶ Creates and returns an instance of the importer specified by
name
.
-
myokit.formats.
importers
()¶ Returns a list of available importers by name.
-
class
myokit.formats.
Importer
¶ Abstract base class for importers.
-
component
(path, model)¶ Imports a component from the given
path
and adds it to the given model.The importer may pose restraints on the used model. For example, the model may be required to contain a variable labelled “membrane_potential”. For details, check the documentation of the individual importers.
The created
myokit.Component
is returned. Amyokit.ImportError
will be raised if any errors occur.
-
model
(path)¶ Imports a model from the given
path
.The created
myokit.Model
is returned. Amyokit.ImportError
will be raised if any errors occur.
-
protocol
(path)¶ Imports a protocol from the given
path
.The created
myokit.Protocol
is returned. Amyokit.ImportError
will be raised if any errors occur.
-
supports_component
()¶ Returns a bool indicating if component import is supported.
-
supports_model
()¶ Returns a bool indicating if model import is supported.
-
supports_protocol
()¶ Returns a bool indicating if protocol import is supported.
-
Exporting¶
-
myokit.formats.
exporter
(name)¶ Creates and returns an instance of the exporter specified by
name
.
-
myokit.formats.
exporters
()¶ Returns a list of available exporters by name.
-
class
myokit.formats.
Exporter
¶ Abstract base class for exporters.
-
_test_writable_dir
(path)¶ Ensures the given path is writable, or raises a
myokit.ExportError
if it can’t be used.
-
model
(path, model)¶ Exports a
myokit.Model
.The output will be stored in the file
path
. Amyokit.ExportError
will be raised if any errors occur.
-
post_export_info
()¶ Optional method that returns a string containing information about this exporter, to be shown after the export is completed.
-
runnable
(path, model, protocol=None, *args)¶ Exports a
myokit.Model
and optionally amyokit.Protocol
to something that can be run or compiled.The output will be stored in the directory
path
. Amyokit.ExportError
will be raised if any errors occur.
-
supports_model
()¶ Returns
True
if this exporter supports model export.
-
supports_runnable
()¶ Returns
True
if this exporter supports export of a model and optional protocol to a runnable piece of code.
-
-
class
myokit.formats.
TemplatedRunnableExporter
¶ Abstract class, extends:
Exporter
Abstract base class for exporters that turn a model (and optionally a protocol) into a runnable chunk of code.
-
_dict
()¶ Returns a dict (filename : template_file_name) containing all the templates used by this exporter.
This should be implemented by each subclass.
-
_dir
(formats_dir)¶ Returns the path to this exporter’s data files (as a string).
This should be implemented by each subclass. The root directory all format extensions are stored in in passed in as ``formats_dir``.
-
_vars
(model, protocol)¶ Returns a dict containing all variables the templates will need.
Will be called with the arguments model and protocol, followed by any extra arguments passed to
runnable()
.This should be implemented by each subclass.
-
runnable
(path, model, protocol=None, *args)¶ Exports a
myokit.Model
and optionally amyokit.Protocol
to something that can be run or compiled.The output will be stored in the directory
path
.
-
supports_runnable
()¶ Returns
True
if this exporter supports export of a model and optional protocol to a runnable piece of code.
-
Expression writers¶
A number of export classes use ExpressionWriter
objects to convert
myokit expressions to string representations in the appropriate language. The
base class for expression writers is described below:
-
myokit.formats.
ewriter
(name)¶ Creates and returns an instance of the expression writer specified by
name
.
-
myokit.formats.
ewriters
()¶ Returns a list of available expression writers by name.
-
class
myokit.formats.
ExpressionWriter
¶ Base class for expression writers, that take myokit expressions as input and convert them to text or other formats.
-
_build_op_map
()¶ Returns a mapping from myokit operators to lambda functions on expr.
-
eq
(q)¶ Converts an equation to a string
-
ex
(e)¶ Converts an Expression to a string.
-
set_lhs_function
(f)¶ - Sets a naming function, will be called to get the variable name from a
myokit.LhsExpression
object.
The argument
f
should be a function that takes anLhsExpression
as input and returns a string.
-
Registering external formats¶
The importers, exporters, and expression writers that are packed with Myokit
are automatically detected at start-up. To register classes defined outside of
the myokit
module, use the functions below. After registering, you can
obtain e.g. an Exporter
via
myokit.formats.exporter(my_external_exporter)
.
-
myokit.formats.
register_external_importer
(name, importer_class)¶ Registers an external
Importer
for use with Myokit.Arguments:
name
- A short descriptive string name.
importer_class
- The class to register (must be a
myokit.Importer
). Importers can be unregistered by passing inNone
.
-
myokit.formats.
register_external_exporter
(name, exporter_class)¶ Registers an external
Exporter
for use with Myokit.Arguments:
name
- A short descriptive string name.
exporter_class
- The class to register (must be a
myokit.Exporter
). Exporters can be unregistered by passing inNone
.
-
myokit.formats.
register_external_ewriter
(name, ewriter_class)¶ Registers an external
ExpressionWriter
for use with Myokit.Arguments:
name
- A short descriptive string name.
ewriter_class
- The class to register (must be a
myokit.ExpressionWriter
). Expression writers can be unregistered by passing inNone
.
Default expression writers¶
Finally, Myokit contains two default expression writers, which are used internally to write expressions in Python format with or without NumPy support.
-
myokit.
python_writer
()¶ Returns a globally shared python expression writer.
LhsExpressions are converted as follows:
- Derivatives are indicated as “_d_” + var.uname()
- Other names are indicated as var.uname()
This convention ensures a unique mapping of a model’s lhs expressions to acceptable python variable names.
-
myokit.
numpy_writer
()¶ Returns a globally shared numpy expression writer.
LhsExpressions are converted as follows:
- Derivatives are indicated as “_d_” + var.uname()
- Other names are indicated as var.uname()
This convention ensures a unique mapping of a model’s lhs expressions to acceptable python variable names.