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 beNone
.
- 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 amyokit.Model
object. Similarly,protocol
can be either amyokit.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 givenmodel
andprotocol
.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()
) asstdout
andstderr
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 ascontext
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 a model state from a file in one of the formats specified by
myokit.parse_state()
.If a
Model
is provided the state will be run throughModel.map_to_state()
and returned as a list of floating point numbers.
- myokit.load_state_bin(filename)¶
Loads a model 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 a model state to the path
filename
.If no
model
is specifiedstate
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 byModel.map_to_state()
and will be stored in the format returned byModel.format_state()
.
- myokit.save_state_bin(filename, state, precision=64)¶
Stores a model state (or any given list of floating point numbers) to the path
filename
, using a binary format.The used format is a zip file, containing a single entry:
state_x_y
, wherex
is the used data type (d
orf
) andy
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.