Reading and writing

This page is about reading and writing the mmt format used by Myokit. For information about using Myokit with other formats, please check out the API :: Formats section.

Myokit models can be loaded form disk using load() and stored using save(). Both these functions assume you’re working with a full (model, protocol, script) tuple. Support for partial loading and saving is provided through functions like load_model() and split().

Similar functions are available to load save model states.

Basic commands

myokit.load(filename)

Reads an mmt file and returns a tuple (model, protocol, embedded script).

If the file specified by filename doesn’t contain one of these parts the corresponding entry in the tuple will be None.

myokit.save(filename=None, model=None, protocol=None, script=None)

Saves a model, protocol, and embedded script to an mmt file.

The model argument can be given as plain text or a myokit.Model object. Similarly, protocol can be either a myokit.Protocol or its textual represenation.

If no filename is given the mmt code is returned as a string.

myokit.parse(source)

Parses strings in mmt format and returns a tuple (model, protocol, embedded script).

None may be returned for any segment not appearing in the source.

The source to parse can be given as a plain string, a sequence of lines or a stream of lines.

myokit.run(model, protocol, script, stdout=None, stderr=None, progress=None)

Runs a python script using the given model and protocol.

The following functions are provided to the script:

get_model()

This returns the model passed to run(). When using the GUI, this returns the model currently loaded into the editor.

get_protocol()

This returns the protocol passed to run(). When using the GUI, this returns the protocol currently loaded into the editor.

Ordinary and error output can be re-routed by providing objects with a file-like interface (x.write(text), x.flush()) as stdout and stderr respectively. Note that output is only re-routed on the python level so that any output generated by C-code will still go to the main process’s output and error streams.

An object implementing the ProgressReporter interface can be passed in. This will be made available globally to any simulations (or other methods) that provide progress update information.

Using parts of mmt files

myokit.load_model(filename)

Loads the model section from an mmt file.

Raises a SectionNotFoundError if no model section is found.

myokit.load_protocol(filename)

Loads the protocol section from an mmt file.

Raises a SectionNotFoundError if no protocol section is found.

myokit.load_script(filename)

Loads the script section from an mmt file.

Raises a SectionNotFoundError if no script section is found.

myokit.split(source)

Attempts to split the source into model, protocol and script segments. Any content before the [[model]] tag is discarded.

myokit.save_model(filename, model)

Saves a model to a file

myokit.save_protocol(filename, protocol)

Saves a protocol to a file

myokit.save_script(filename, script)

Saves an embedded script to a file

Default mmt file parts

When generating new mmt files, default protocols and scripts can be inserted:

myokit.default_protocol(model=None)

Returns a default protocol to use when no embedded one is available.

myokit.default_script(model=None)

Returns a default script to use when no embedded script is available.

Parsing parts mmt files

myokit.parse_model(source)

Parses a model in mmt format.

myokit.parse_protocol(source)

Parses a protocol in mmt format.

Parsing expressions

myokit.parse_expression(string, context=None)

Parses string data into a myokit.Expression.

A myokit.Variable object can be given as context to resolve any references against.

Parsing units

myokit.parse_unit(string)

Parses string data into a myokit.Unit.

Parse errors

Errors with the underlying file system (file not found, file corrupt etc) will result in ordinary Python IO errors. Any other errors occurring during parsing should be of the type ParseError.

myokit.format_parse_error(ex, source=None)

Turns a ParseError ex into a detailed error message.

If a filename or input stream is passed in as source, this will be used to show the line on which an error occurred. If a stream is passed, it should be rewinded to the same point the original parsing started.

Loading and saving states

myokit.load_state(filename, model=None)

Loads an initial state from a file in one of the formats specified by myokit.parse_state().

If a Model is provided the state will be run through Model.map_to_state() and returned as a list of floating point numbers.

myokit.load_state_bin(filename)

Loads an initial state from a file in the binary format used by myokit. See save_state_bin() for details.

myokit.save_state(filename, state, model=None)

Stores the given state in the file at filename.

If no model is specified state should be given as a list of floating point numbers and will be stored by simply placing each number on a new line.

If a Model is provided the state can be in any format accepted by Model.map_to_state() and will be stored in the format returned by Model.format_state().

myokit.save_state_bin(filename, state, precision=64)

Stores the given state (or any list of floating point numbers) in the file at filename, using a binary format.

The used format is a zip file, containing a single entry: state_x_y, where x is the used data type (d or f) and y is the number of entries. All entries are stored little-endian.

myokit.parse_state(state)

Parses an initial state declaration given in one of two formats:

<var_name_1> = <value>
<var_name_1> = <value>
...

Blank lines, whitespace and indentation are ignored. All variable names must be given fully qualified. Parsed data from this format is returned as a dictionary mapping variable names to values.

Alternatively, the input can be given as a list of floating point numbers separated by spaces, commas, semi-colons, line breaks etc:

<value>
<value>
...

Parsed data from this input format is returned as a list of floating point numbers.

A note about the format

The mmt format consists of several sections (each with their own syntax) stored sequentially in a single, string-based format. In theory, this means mmt files containing syntax errors cannot be reliably separated into parts. For example if a string isn’t terminated in one section, it is impossible to tell if a subsequent section header indicates a new section or is part of the string.

These problems could be avoided in a more complicated format, for example a zip file containing separate files for each section. However, using a plain-text format makes mmt files human readable, loadable in any text editor and directly suitable for storage in versioning systems.