Export formats

The following formats can be generated by Heta Compiler.

• JSON
• YAML
• Canonical
• HetaCode
• DynMS
• DBSolve
• SLV
• SBML
• Simbio
• Mrgsolve
• Table
• XLSX
• Julia
• Matlab
• Dot
• Summary

See also Features support table

Declaration exports

There are two ways to export models in Heta Compiler: using the export property in the declaration file or using the CLI --export option. If no --export option is set, the compiler will use the export property from the declaration file.

The export property is an array of objects with the format and filepath properties and other format-specific properties.

• format is a string with the name of the format. Format matching is case-insensitive. The list of supported formats is below.
• filepath is an optional property, which is a string with the path to the output directory. The path is relative to the output (dist) directory.
• spaceFilter is an optional property, which is a string with a regular expression to select namespaces for export. If not set, all namespaces will be exported. For exporters that require concrete namespaces, only namespaces with abstract: false will be exported.

Example

{
    export: [
        {
            format: JSON,
            filepath: output,
            omit: ['aux.wiki'],
            useUnitsExpr: false,
            spaceFilter: "nameless|another"
        },
        {
            format: SBML,
            version: L2V4,
            filepath: model
        },
        {
            format: Table
        }
    ]
}

Instead of the export property in the declaration file, one can use the CLI --export option. The option is a comma-separated list of format names. The list also supports structures in JSON-like format. If the --export option is set, the compiler will ignore the export property in the declaration file.

Example

heta build --export '{format: JSON, filepath: output, omit: ["aux.wiki"], spaceFilter: "nameless|another"}, {format: SBML, version: L2V4, filepath: model}, Table'

Inline export (deprecated)

In older versions of Heta compiler, inline export in any .heta file was supported.

Example 1

#export {format: JSON, filepath: output};

Starting from heta-compiler version 0.9.0 the inline export is deprecated. Use the export property in the declaration file or the CLI --export option. See migrate to v0.9 and CLI references for details.

JSON

Export to a JSON structure (array) storing the content of the whole platform or selected namespaces (see the spaceFilter option) in Heta JSON format. Can work with abstract namespaces.

Properties

property	type	required	default	ref	description
omit	string[]				Array of properties paths to exclude from output.
useUnitsExpr	boolean		false		If false or not set, units will be written in Unit array format. If true, units will be written in UnitsExpr format.

Output files

[filepath]/output.heta.json : all content created for selected spaces.

Example

{
    format: JSON,
    filepath: output,    # save result in directory "dist/output"
    omit: [aux.wiki],    # omit aux.wiki properties from components
    useUnitsExpr: false, # save units in Unit array format
    spaceFilter: "nameless|another" # only content from "nameless" and "another" namespaces will be exported
}

YAML

Export to a YAML structure (array) storing the content of the whole platform or selected namespaces (see the spaceFilter option) in Heta YAML format. Can work with abstract namespaces.

Properties

property	type	required	default	ref	description
omit	string[]				Array of properties paths to exclude from output.
useUnitsExpr	boolean		false		If false or not set, units will be written in Unit array format. If true, units will be written in UnitsExpr format.

Output files

[filepath]/output.heta.yml : all content created for selected spaces.

Example

{
    format: YAML,
    filepath: output,    # rewrite target directory to "dist/output"
    omit: [aux.wiki],    # omit aux.wiki properties from components
    useUnitsExpr: false, # save units in Unit array format
    spaceFilter: ".+"    # all namespaces
}

Canonical

Export the whole platform content in canonical JSON format. The output is the same as for JSON format, but the components and internal properties are grouped and sorted. This is useful for debugging and comparing models: it generates the same output for the same model regardless of the order of components in declaration files and other factors.

Properties

No additional properties

Output files

[filepath]/output.heta.json : all content created for selected spaces.

Known restrictions

• Math expressions are presented as strings without any transformations. For example, x^y will be exported as x^y and not transformed to canonical form pow(x, y).
• Units are presented in format of UnitsExpr and not transformed or substituted by the values of #defineUnit.

Example

{ format: Canonical, filepath: canonical } # result in dist/canonical

HetaCode

Export selected namespaces to Heta code. Can work with abstract namespaces.

Properties

No additional properties

Output files

[filepath]/output.heta : Heta code for selected namespaces.

Example

{ format: HetaCode, filepath: heta-code }

DynMS

Export to DynMS (Dynamic Model Specifications) format which is an experimental format for executable dynamic models, designed to support reproducible mechanistic workflows, code generation, and interoperability across simulation tools.

Properties

property	type	required	default	ref	description
exprFormat	"math-json" / "heta" / "c" / "julia"		"math-json"		The format of mathematical expressions in the exported model. "heta" means that the expressions will be exported in the same format as they are defined in Heta.

Output files

[filepath]/output.dynms.json : all content created for selected spaces in DynMS format.

Example

{
    format: DynMS,
    filepath: dynms,       # save result in directory "dist/dynms"
    spaceFilter: nameless, # output everything from nameless namespace
    exprFormat: julia      # export math expressions in Julia code format
}

DBSolve

Export to DBSolve format which is the model format for DBSolveOptimum.

This is the recommended version of the SLV export format. It supports time-varying compartment volumes and record initialization by arbitrary expressions.

Properties

property	type	required	default	ref	description
powTransform	"keep" / "operator" / "function"		"keep"		Controls whether x^y and pow(x, y) are transformed.
groupConstBy	string/path		tags[0]		How to group constants in Initial Values of the DBSolve file. Should be written as a JSON path.
version	string		26		SLV file version: 26 (for DBSolveOptimum 2020) or 25 (for earlier versions)

Output files

[filepath]/[namespace].slv : model created from the namespace, which can be opened by DBSolveOptimum.

Known restrictions

• Infinity, -Infinity, NaN values are not supported
• boolean operators like and, or, etc. are not supported
• DSwitcher supports only simple comparison operators in trigger.
• CSwitcher is transformed to DSwitcher-like step detection, so root finding is not supported.

Example

{
    format: DBSolve,
    filepath: model,       # save results in directory "dist/model"
    spaceFilter: nameless, # namespace used for model generation
    powTransform: keep,     # use x^y and pow(x, y) without changes
    version: "25"
}

SLV

Deprecated old version. Use DBSolve export when possible.

Export to SLV format which is the model format for DBSolveOptimum. This exporter keeps the older SLV structure and supports only a limited subset of Heta models.

Properties

property	type	required	default	ref	description
eventsOff	boolean				If eventsOff = true, switchers will not be exported to DBSolve events.
powTransform	"keep" / "operator" / "function"		"keep"		Controls whether x^y and pow(x, y) are transformed.
groupConstBy	string/path		tags[0]		How to group constants in Initial Values of the DBSolve file. Should be written as a JSON path.
version	string		26		SLV file version: 26 (for DBSolveOptimum 2020) or 25 (for earlier versions)

Output files

[filepath]/[namespace].slv : model created from the namespace, which can be opened by DBSolveOptimum.

Known restrictions

• Compartment which changes in time may result in wrong ODE.
• CSwitcher and DSwitcher are not supported and are ignored in the generated SLV file.
• TimeSwitcher supports only event assignments which can be represented as a * x + b, where x is the target record and a, b are numbers or direct identifiers. For example, x [sw1] = 2 * x + 1 is supported, but x [sw1] = x + 1 / c1 is not supported.
• Unsupported switchers or event assignments are reported as export errors, but the generated SLV structure is kept valid.
• Initialization of Record by expression does not work: x1 .= k1 * A is not supported.
• Infinity, -Infinity, NaN values are not supported
• boolean operators like and, or, etc. are not supported

Example

{
    format: SLV,
    filepath: model,           # save results in directory "dist/model"
    spaceFilter: "^nameless$", # namespace used for model generation
    eventsOff: false,          # all switchers will be transformed to DBSolve events
    powTransform: keep,        # use x^y and pow(x, y) without changes
    groupConstBy: "tags[1]"    # use the second tag
}

SBML

Export to SBML format.

Properties

property	type	required	default	ref	description
version	string		L2V4		SBML version in format: L2V4. Possible values are L2V3, L2V4, L2V5, L3V1, L3V2

Output files

[filepath]/[namespace].xml : SBML formatted model

Known restrictions

• Older SBML versions may not support all Heta features. Compatibility was checked for L3V2.
• SBML format does not support TimeSwitcher and CSwitcher. They will be transformed to DSwitcher with settings that give approximate behavior.
• SBML older than L3V1 does not support initialValue in <trigger> so atStart property of CSwitcher and DSwitcher will not be applied.
• In SBML there is no way to clarify if the switcher works in "root finding" mode. We assume that the switcher works in "step" mode, although other implementations may exist in the SBML ecosystem.

Example:

{
    format: SBML,
    filepath: model,       # save results in directory "dist/model"
    spaceFilter: nameless, # namespace used for model generation
    version: L2V4          # Level 2 Version 4
}

Simbio

Export to SimBiology/Matlab code (m files). The code can be run to create a SimBiology project.

Properties

property	type	required	default	ref	description
auxAsNotes	boolean		false		If true, aux content will be appended to Simbio Notes as JSON object

Output files

[filepath]/[namespace].m : Code which can be run in Matlab environment to generate a Simbio model. [filepath]/tern__.m : Auxiliary mathematical function to support Simbio code. This code should be placed in the same directory as the Simbio project.

Known restrictions

• TimeSwitcher and CSwitcher are transformed to DSwitcher with settings that give approximate behavior. The precision of switching time depends on the solver maxstep parameter, so you may need to set maxstep to a small value.
• DSwitcher in Simbio does not support the atStart property. The solver always acts as if it is set to false.

Example:

{
    format: Simbio,
    filepath: model,       # save results in directory "dist/model"
    spaceFilter: nameless  # namespace used for model generation
}

Mrgsolve

Export to mrgsolve model format.

Properties

No additional properties

Output files

[filepath]/[namespace].cpp : Code which can be run in mrgsolve environment. [filepath]/run.r : Code for fast run.

Known restrictions

• CSwitcher works without root finding.
• Both CSwitcher and DSwitcher can trigger only with delta precision. So you need to set delta to a small value to have more precise switching time. For example, delta = 1e-3 will give you millisecond precision for switching time. Update of hmax solution parameter in mrgsolve may also help to improve precision.
• If expressions inside @Record depend explicitly on time t, the simulation may give incorrect results. To fix it, you should replace TIME variable in $ODE block by SOLVERTIME manually in model.cpp. It will be fixed in future versions.

Example:

{
    format: Mrgsolve,
    filepath: model,      # save results in directory "dist/model"
    spaceFilter: nameless # namespace used for model generation
}

Table

Export platform content in tabular format: CSV, Excel, etc. The format of tables corresponds to the tabular (xlsx) heta module. It can be loaded as a module in other projects. Can work with abstract namespaces.

This format combines a series of formats supported by the https://www.npmjs.com/package/xlsx library. For the list of supported files see the docs https://github.com/SheetJS/sheetjs#supported-output-formats.

Properties

property	type	required	default	ref	description
omitRows	number				If set, this creates empty rows in output sheets.
omit	string[]				Array of properties paths to exclude from output.
bookType	string		csv		One of the supported file types, see xlsx docs.
splitByClass	boolean				If true, the components will be split by class and saved as several sheets or files: one sheet/file per class.

bookType

Multi-sheet formats	Single-sheet formats
xlsx (.xlsx), xlsm (.xlsm), xlsb (.xlsb), biff8 (.xls),	wk3 (.wk3), csv (.csv), txt (.txt), sylk (.sylk),
biff5 (.xls), biff4 (.xls), biff3 (.xls), biff2 (.xls),	html (.html), dif (.dif), dbf (.dbf), wk1 (.dbf),
xlml (.xls), ods (.ods), fods (.fods)	rtf (.rtf), prn (.prn), eth (.eth)

Output files

[filepath]/output.heta.[extension] : Table file. The extension depends on the bookType property. or [filepath]/[sheet].heta.[extension] : If you use CSV and similar one-page file types.

Example 1:

{ format: Table, filepath: platform }

Example 2:

{
    format: Table,
    filepath: output,      # save result in directory "dist/output"
    spaceFilter: nameless, # output everything from nameless namespace
    omitRows: 5,           # include 5 empty rows between header and the first line
    omit: [aux.wiki],      # omit aux.wiki properties from components
    bookType: html         # save as HTML table
}

XLSX

Creation of an Excel file (.xlsx). This works in the same way as the Table format with bookType: xlsx. Can work with abstract namespaces.

Properties

Same as Table, except bookType is always xlsx.

Output files

[filepath]/output.heta.xlsx : File which can be opened in Excel.

Example:

{
    format: XLSX,
    filepath: output, // save result in directory "dist/output"
    omitRows: 3, // include 3 empty rows between header and the first line
    omit: [aux.wiki], // omit aux.wiki properties from components
    splitByClass: true // split classes to different sheets
}

Julia

Creation of Julia files (.jl). Currently used internally by HetaSimulator.jl.

Properties

No additional properties

Output files

[filepath]/model.jl : File storing model code for all namespaces. [filepath]/run.jl : Code to run model.

Example:

{
    format: Julia,
    filepath: julia_code, # save result in directory "dist/julia_code"
    spaceFilter: nameless # create model based on nameless namespace
}

Matlab

Creation of Matlab files (.m) which represent ODE and code to run ODE.

Properties

No additional properties

Output files

[filepath]/[namespace]_model.m : File storing model code. [filepath]/[namespace]_param.m : Constants initialization. [filepath]/[namespace]_run.m : Code to run model.

Known restrictions

• DSwitcher and TimeSwitcher are not supported directly. They are transformed to CSwitcher with settings that give approximate behavior.
• The atStart property is not supported for CSwitcher and DSwitcher. The solver always acts as if it is set to false.
• Unstable behavior may occur when two or more switchers run simultaneously.

Example:

{
    format: Matlab,
    filepath: matlab_code,              # save result in directory "dist/matlab_code"
    spaceFilter: (nameless|another_one) # create two models based on namespaces
}

Dot

Export namespaces to graphs in DOT format (see details at https://graphviz.org/). Each namespace is exported to a separate file.

Properties

No additional properties

Output files

[filepath]/[namespace].dot : File storing graph code.

Example:

{
    format: Dot,
    filepath: schemes, # save result in directory "dist/schemes"
}

Summary

Summarize model content and present statistics of the model components. It can also be used to debug the model.

Properties

No additional properties

Output files

[filepath]/platform.md : File storing model summary.

Example:

{ format: Summary, filepath: summary }

Features support

	SLV	DBSolve	Julia	Mrgsolve/R	Matlab	Simbio/Matlab	SBML (L3V2)	JSON, YAML	Table	Dot	DynMS
@UnitDef class	na	na	na	na	na	+	+	+	+	na	na
@TimeSwitcher class	+ (limited assignments)	+	+	+	+ (converts to DSwitcher)	+	+ (converts to DSwitcher)	+	+	na	+
@TimeSwitcher {start: 6}	+	+	+	+	+	+	+	+	+	na	+
@TimeSwitcher {start: 0}	+	+	+	+	+	+	+	+	+	na	+
@TimeSwitcher {start: time_start} with ref to @Const	+	+	+	+	+	+	+	+	+	na	+
@TimeSwitcher {period: 12} infinite repeat	+	+	+	+	+	+	+	+	+	na	+
@TimeSwitcher {stop: 120} stop time for repeat	+	+	+	+	+	+	+	+	+	na	+
@CSwitcher class	-	+ (converts to DSwitcher)	+	+	+	+	+(converts to DSwitcher)	+	+	na	+
@CSwitcher root finding	-	-	+	-	+	+	-	na	na	na	+
@DSwitcher class	-	+	+	+	+ (converts to DSwitcher)	+	+	+	+	na	+
atStart in @CSwitcher and @DSwitcher	-	+	+	+	- (never run at 0)	- (never run at 0)	+ (use initialValue in trigger)	+	+	na	+
MathExpr: arithmetic functions	+	+	+	+	+	+	+	+	+	na	+
MathExpr: boolean operators	-	-	+	+	+	+	+	+	+	na	+
MathExpr: ternary operator	+	+	+	-	+	+	+	+	+	na	+
MathExpr: piecewise function	-	-	+	-	+	+	+	+	+	na	+
MathExpr: e, pi	+	+	+	+	+	+	+	+	+	na	+
MathExpr: Infinity, NaN	-	-	+	+	+	+	+	+	+	na	+
Const: Infinity, NaN	-	-	+	+	+	+	+	+	+	na	-
@Scenario support	-	-	-	-	-	-	-	+	+	na	-
@Record {ss: true, ...}	-	-	+	-	-	-	-	+	+	na	+
#defineFunction	+(sub)	+(sub)	+	+(sub)	+	+(sub)	+	+	+	na	+(sub)

(sub) means that the function will be substituted by its body in the output code.

(?) means that the support depends on the specific case or need to be checked.

na means "not applicable", for example, @Scenario or @UnitDef is not applicable for DBSolve.

Math expressions conversions

Skipped cell means no conversion

	SLV/DBSolve	Julia	Mrgsolve/R	Simbio/Matlab
abs(x)			fabs(x)
add(x, y)	x + y	+(x, y)
ceil(x)
cube(x)	pow(x, 3) or x ^ 3	NaNMath.pow(x, 3)
divide(x, y)	x / y	/(x, y)
exp(x)
floor(x)
ln(x)		NaNMath.log(x)
log(x)		NaNMath.log(x)		log(x)
logbase(x, base)	log(x) / log(base)	NaNMath.log(base, x)		(log(x)/log(base))
log10(x)		NaNMath.log10(x)
log2(x)	log(x) / log(2)	NaNMath.log2(x)		(log(x)/log(2))
multiply(x, y)	x * y	*(x, y)
pow(x, y)	pow(x, y) or x ^ y	NaNMath.pow(x, y)		power(x, y)
sign(x)
sqrt(x)		NaNMath.sqrt(x)
nthRoot(x, n)	pow(x, 1 / n) or x ^ (1 / n)	NaNMath.pow(x, 1/(n))
square(x)	pow(x, 2) or x ^ 2	NaNMath.pow(x, 2)
subtract(x, y)	x - y	-(x, y)
max(x, y)	max2(x, y)		std::max(x, y)	max(x, y)
max(x, y, z)	max3(x, y, z)		std::max(x, y, z)	max([x, y, z])
min(x, y)	min2(x, y)		std::min(x, y)	min(x, y)
min(x, y, z)	min3(x, y, z)		std::min(x, y, z)	min([x, y, z])
factorial(n)		fact(n)
ifgt(x, y, z1, z2)		x > y ? z1 : z2		tern__(x>y, z1, z2)
ifge(x, y, z1, z2)		x >= y ? z1 : z2		tern__(x>=y, z1, z2)
iflt(x, y, z1, z2)		x < y ? z1 : z2		tern__(x<y, z1, z2)
ifle(x, y, z1, z2)		x <= y ? z1 : z2		tern__(x<=y, z1, z2)
ifeq(x, y, z1, z2)		x == y ? z1 : z2		tern__(x==y, z1, z2)
x ^ y	x ^ y or pow(x, y)	NaNMath.pow(x, y)	pow(x, y)	(x ^ y)
e	exp(1)	exp(1.0)
pi	acos(-1)
Infinity		Inf
NaN		NaN
t			TIME	time
a and b		a && b	a && b	a & b
a or b		a || b	a || b	a | b
a xor b		xor(a, b)	xor(a, b)	xor(a, b)
not a		!a	!a	~a
b1 < b2 ? x : y	iflt(b1, b2, x, y)	(b1 < b2) ? x : y	(b1 < b2) ? x : y	tern__(b1 < b2, x, y)
piecewise(value1, cond1, value2, cond2, ..., otherwise)	not supported	+	not supported
acos(x), acot(x), acsc(x),asec(x), asin(x), atan(x), cos(x), cot(x), csc(x), sec(x), sin(x), tan(x)

Conversion to SBML's MathML

	SBML
abs(x)	<apply><abs/>(x)</apply>
add(x, y)	<apply><plus/>(x) (y)</apply>
ceil(x)	<apply><ceiling/>(x)</apply>
cube(x)	<apply><power/>(x)<cn>3</cn></apply>
divide(x, y)	<apply><divide/>(x) (y)</apply>
exp(x)	<apply><exp/>(x)</apply>
floor(x)	<apply><floor/>(x)</apply>
ln(x)	<apply><ln/>(x)</apply>
log(x)	<apply><ln/>(x)</apply>
logbase(x, base)	<apply><log/><logbase>(base)</logbase>(x)</apply>
log10(x)	<apply><log/>(x)</apply>
log2(x)	<apply><log/><logbase><cn>2</cn></logbase>(x)</apply>
multiply(x, y)	<apply><times/>(x) (y)</apply>
pow(x, y)	<apply><power/>(x) (y)</apply>
sign(x)	<apply><sign/>(x)</apply>
sqrt(x)	<apply><root/>(x)</apply>
nthRoot(x, n)	<apply><root/><degree>(n)</degree>(x)</apply>
square(x)	<apply><power/>(x)<cn>2</cn></apply>
subtract(x, y)	<apply><minus/>(x) (y)</apply>
max(x, y)	<apply><max/>(x) (y)</apply>
max(x, y, z)	<apply><max/>(x) (y) (z)</apply>
min(x, y)	<apply><min/>(x) (y)</apply>
min(x, y, z)	<apply><min/>(x) (y) (z)</apply>
factorial(n)	<apply><factorial/>(n)</apply>
ifgt(x, y, z1, z2)	not supported
ifge(x, y, z1, z2)	not supported
iflt(x, y, z1, z2)	not supported
ifle(x, y, z1, z2)	not supported
ifeq(x, y, z1, z2)	not supported
x ^ y	<apply><power/>(x) (y)</apply>
e	<exponentiale/>
pi	<pi/>
Infinity	<infinity/>
NaN	<notanumber/>
t	<csymbol definitionURL="http://www.sbml.org/sbml/symbols/time">t</csymbol>
a and b	<apply><and/>(a) (b)</apply>
a or b	<apply><or/>(a) (b)</apply>
a xor b	<apply><xor/>(a) (b)</apply>
not a	<apply><not/>(a)</apply>
b1 < b2 ? x : y	<piecewise><piece>(x)<apply><lt/>(b1) (b2)</apply></piece><otherwise>(y)</otherwise></piecewise>
piecewise(value1, cond1, value2, cond2, ..., otherwise)	<piecewise><piece>(value1) (cond1)</piece><piece>(value2) (cond2)</piece><otherwise>(otherwise)</otherwise></piecewise>
acos(x), acot(x), acsc(x),asec(x), asin(x), atan(x), cos(x), cot(x), csc(x), sec(x), sin(x), tan(x)	<apply><arccos/>(x)</apply>...