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. A myokit.ImportError will be raised if any errors occur.

model(path)

Imports a model from the given path.

The created myokit.Model is returned. A myokit.ImportError will be raised if any errors occur.

protocol(path)

Imports a protocol from the given path.

The created myokit.Protocol is returned. A myokit.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. A myokit.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 a myokit.Protocol to something that can be run or compiled.

The output will be stored in the directory path. A myokit.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 a myokit.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 an LhsExpression 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 in None.
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 in None.
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 in None.

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:

  1. Derivatives are indicated as “_d_” + var.uname()
  2. 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:

  1. Derivatives are indicated as “_d_” + var.uname()
  2. Other names are indicated as var.uname()

This convention ensures a unique mapping of a model’s lhs expressions to acceptable python variable names.