Skip to content

Modules

libvcell

MathRegeneration

Bases: BaseModel

Which applications of a document had their math regenerated, and why the others failed.

Attributes:

Name Type Description
regenerated list[str]

names of the applications whose math was regenerated, in document order.
failed dict[str, str]

application name -> reason, for each application whose math generation failed; such an application keeps the math it was stored with.
Source code in libvcell/model_utils.py 
127
128
129
130
131
132
133
134
135
136
137
class MathRegeneration(BaseModel):
    """Which applications of a document had their math regenerated, and why the others failed.

    Attributes:
        regenerated: names of the applications whose math was regenerated, in document order.
        failed: application name -> reason, for each application whose math generation failed; such an
            application keeps the math it was stored with.
    """

    regenerated: list[str]
    failed: dict[str, str]

VCellExpressionError

Bases: Exception

Raised when a VCell expression cannot be evaluated.

Attributes:

Name Type Description
error_type

the originating Java exception's simple class name (e.g. DivideByZeroException, ExpressionBindingException, ParseException, FunctionDomainException), or None.
message

the error message, or None.
Source code in libvcell/model_utils.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class VCellExpressionError(Exception):
    """Raised when a VCell expression cannot be evaluated.

    Attributes:
        error_type: the originating Java exception's simple class name (e.g. ``DivideByZeroException``,
            ``ExpressionBindingException``, ``ParseException``, ``FunctionDomainException``), or ``None``.
        message: the error message, or ``None``.
    """

    def __init__(self, error_type: str | None, message: str | None) -> None:
        self.error_type = error_type
        self.message = message
        super().__init__(f"{error_type}: {message}")

evaluate_expression(expression_infix, symbol_table)

Evaluate a native-syntax VCell infix expression against a table of symbol values.

Any symbol referenced by the expression must be present in symbol_table; extra (unreferenced) symbols are permitted and ignored.

Parameters:

Name Type Description Default
expression_infix str

native VCell infix expression string (e.g. "a + b/c")

 required
symbol_table dict[str, float]

mapping of symbol name to 64-bit float value

 required

Returns:

Name Type Description
float float

the evaluated value

Raises:

Type Description
VCellExpressionError

if the expression fails to parse, references an unsupplied symbol, fails to evaluate (e.g. division by zero, math domain error), or evaluates to a non-finite value.
Source code in libvcell/model_utils.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def evaluate_expression(expression_infix: str, symbol_table: dict[str, float]) -> float:
    """
    Evaluate a native-syntax VCell infix expression against a table of symbol values.

    Any symbol referenced by the expression must be present in ``symbol_table``; extra
    (unreferenced) symbols are permitted and ignored.

    Args:
        expression_infix (str): native VCell infix expression string (e.g. ``"a + b/c"``)
        symbol_table (dict[str, float]): mapping of symbol name to 64-bit float value

    Returns:
        float: the evaluated value

    Raises:
        VCellExpressionError: if the expression fails to parse, references an unsupplied symbol,
            fails to evaluate (e.g. division by zero, math domain error), or evaluates to a
            non-finite value.
    """
    native = VCellNativeCalls()
    result: EvalReturnValue = native.evaluate_expression(expression_infix, symbol_table)
    if not result.success or result.value is None:
        raise VCellExpressionError(result.error_type, result.message)
    return result.value

sbml_to_finite_volume_input(sbml_content, output_dir_path)

Convert SBML content to finite volume input files

Parameters:

Name Type Description Default
sbml_content str

SBML content

 required
output_dir_path Path

output directory path

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/solver_utils.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def sbml_to_finite_volume_input(sbml_content: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert SBML content to finite volume input files

    Args:
        sbml_content (str): SBML content
        output_dir_path (Path): output directory path

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.sbml_to_finite_volume_input(sbml_content, output_dir_path)
    return return_value.success, return_value.message

sbml_to_ode_input(sbml_content, output_dir_path, duration, output_time_step)

Convert a non-spatial SBML model to Sundials ODE solver input (a CVODE or IDA input file)

The model's first application is simulated from 0 to duration, saving every output_time_step, on the Combined IDA/CVODE solver. Solve the input with the pyvcell-odesolver package.

Parameters:

Name Type Description Default
sbml_content str

SBML content

 required
output_dir_path Path

output directory path

 required
duration float

end time of the simulation (positive)

 required
output_time_step float

interval between saved time points (positive)

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: the success status, and the input file's name on success or the error message
Source code in libvcell/solver_utils.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def sbml_to_ode_input(
    sbml_content: str, output_dir_path: Path, duration: float, output_time_step: float
) -> tuple[bool, str]:
    """
    Convert a non-spatial SBML model to Sundials ODE solver input (a CVODE or IDA input file)

    The model's first application is simulated from 0 to ``duration``, saving every ``output_time_step``,
    on the Combined IDA/CVODE solver. Solve the input with the pyvcell-odesolver package.

    Args:
        sbml_content (str): SBML content
        output_dir_path (Path): output directory path
        duration (float): end time of the simulation (positive)
        output_time_step (float): interval between saved time points (positive)

    Returns:
        tuple[bool, str]: the success status, and the input file's name on success or the error message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.sbml_to_ode_input(sbml_content, duration, output_time_step, output_dir_path)
    return return_value.success, return_value.message

sbml_to_vcml(sbml_content, vcml_file_path)

Convert SBML content to finite volume input files

Parameters:

Name Type Description Default
sbml_content str

SBML content

 required
vcml_file_path Path

path to resulting VCML file

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/model_utils.py 
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def sbml_to_vcml(sbml_content: str, vcml_file_path: Path) -> tuple[bool, str]:
    """
    Convert SBML content to finite volume input files

    Args:
        sbml_content (str): SBML content
        vcml_file_path (Path): path to resulting VCML file

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.sbml_to_vcml(sbml_content=sbml_content, vcml_file_path=vcml_file_path)
    return return_value.success, return_value.message

vcell_infix_to_num_expr_infix(vcell_infix)

Converts an infix string version of a VCell Native Expression, and converts it to a NumExpr compatible version

Parameters:

Name Type Description Default
vcell_infix str

the infix to convert

 required

Returns:

Type Description
tuple[bool, str, str]

tuple[bool, str, str]: A tuple containing the success status, a message, and the converted infix
Source code in libvcell/model_utils.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
def vcell_infix_to_num_expr_infix(vcell_infix: str) -> tuple[bool, str, str]:
    """
    Converts an infix string version of a VCell Native Expression, and converts it to a NumExpr compatible version

    Args:
        vcell_infix (str): the infix to convert

    Returns:
        tuple[bool, str, str]: A tuple containing the success status, a message, and the converted infix
    """
    native = VCellNativeCalls()
    target_num_expr_infix = MutableString("")
    return_value: ReturnValue = native.vcell_infix_to_num_expr_infix(vcell_infix, target_num_expr_infix)
    return return_value.success, return_value.message, target_num_expr_infix.value

vcell_infix_to_python_infix(vcell_infix)

Converts an infix string version of a VCell Native Expression, and converts it to a Python compatible version

Parameters:

Name Type Description Default
vcell_infix str

the infix to convert

 required

Returns:

Type Description
tuple[bool, str, str]

tuple[bool, str, str]: A tuple containing the success status, a message, and the converted infix
Source code in libvcell/model_utils.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def vcell_infix_to_python_infix(vcell_infix: str) -> tuple[bool, str, str]:
    """
    Converts an infix string version of a VCell Native Expression, and converts it to a Python compatible version

    Args:
        vcell_infix (str): the infix to convert

    Returns:
        tuple[bool, str, str]: A tuple containing the success status, a message, and the converted infix
    """
    native = VCellNativeCalls()
    target_python_infix = MutableString("")
    return_value: ReturnValue = native.vcell_infix_to_python_infix(vcell_infix, target_python_infix)
    return return_value.success, return_value.message, target_python_infix.value

vcml_convert_units(vcml_content, unit_system, vcml_file_path)

Rewrite a VCML document in another model unit system, converting every quantity (geometry included)

For an SBML model, import it with :func:sbml_to_vcml first; VCell imports SBML in the SBML's own units.

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
unit_system str

"vcell" (µm, µM, s; what VCell's spatial and stochastic math assumes) or "sbml" (the units VCell writes SBML in)

 required
vcml_file_path Path

path to resulting VCML file

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/model_utils.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def vcml_convert_units(vcml_content: str, unit_system: str, vcml_file_path: Path) -> tuple[bool, str]:
    """
    Rewrite a VCML document in another model unit system, converting every quantity (geometry included)

    For an SBML model, import it with :func:`sbml_to_vcml` first; VCell imports SBML in the SBML's own units.

    Args:
        vcml_content (str): VCML content
        unit_system (str): "vcell" (µm, µM, s; what VCell's spatial and stochastic math assumes) or "sbml"
            (the units VCell writes SBML in)
        vcml_file_path (Path): path to resulting VCML file

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_convert_units(
        vcml_content=vcml_content, unit_system=unit_system, vcml_file_path=vcml_file_path
    )
    return return_value.success, return_value.message

vcml_regenerate_math(vcml_content, vcml_file_path)

Regenerate the math of every application of a VCML document, as VCell does when it upgrades an old document, and write the result.

Unlike vcml_to_vcml, this forces VCell's upgrade (SimulationContext.updateAll(true)): a non-spatial application that gives no absolute structure size gets the sizes VCell's StructureSizeSolver computes from its surface-to-volume ratios and volume fractions (the model's first structure anchored at 1), written into its structure mappings. Each application is regenerated on its own, so one whose math generation fails does not stop the others.

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
vcml_file_path Path

path to resulting VCML file

 required

Returns:

Type Description
tuple[bool, str, MathRegeneration | None]

tuple[bool, str, MathRegeneration | None]: the success status (the document was read and written), a message ("Success", or the error), and on success which applications were regenerated and which failed
Source code in libvcell/model_utils.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def vcml_regenerate_math(vcml_content: str, vcml_file_path: Path) -> tuple[bool, str, MathRegeneration | None]:
    """
    Regenerate the math of every application of a VCML document, as VCell does when it upgrades an old document,
    and write the result.

    Unlike ``vcml_to_vcml``, this forces VCell's upgrade (``SimulationContext.updateAll(true)``): a non-spatial
    application that gives no absolute structure size gets the sizes VCell's ``StructureSizeSolver`` computes from
    its surface-to-volume ratios and volume fractions (the model's first structure anchored at 1), written into its
    structure mappings. Each application is regenerated on its own, so one whose math generation fails does not stop
    the others.

    Args:
        vcml_content (str): VCML content
        vcml_file_path (Path): path to resulting VCML file

    Returns:
        tuple[bool, str, MathRegeneration | None]: the success status (the document was read and written), a
            message ("Success", or the error), and on success which applications were regenerated and which failed
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_regenerate_math(vcml_content=vcml_content, vcml_file_path=vcml_file_path)
    if not return_value.success:
        return False, return_value.message, None
    return True, "Success", MathRegeneration.model_validate_json(return_value.message)

vcml_to_finite_volume_input(vcml_content, simulation_name, output_dir_path)

Convert VCML content to finite volume input files

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
simulation_name str

simulation name

 required
output_dir_path Path

output directory path

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/solver_utils.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
def vcml_to_finite_volume_input(vcml_content: str, simulation_name: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert VCML content to finite volume input files

    Args:
        vcml_content (str): VCML content
        simulation_name (str): simulation name
        output_dir_path (Path): output directory path

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_finite_volume_input(vcml_content, simulation_name, output_dir_path)
    return return_value.success, return_value.message

vcml_to_moving_boundary_input(vcml_content, simulation_name, output_dir_path)

Convert VCML content to Moving Boundary solver input (a MovingBoundarySetup XML file)

The named simulation must be configured for the Moving Boundary solver. The generated MovingBoundarySetup XML can be consumed by the vcell-mbsolver package (MovingBoundarySolver.from_xml).

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
simulation_name str

simulation name (must use the Moving Boundary solver)

 required
output_dir_path Path

output directory path

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/solver_utils.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def vcml_to_moving_boundary_input(vcml_content: str, simulation_name: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert VCML content to Moving Boundary solver input (a MovingBoundarySetup XML file)

    The named simulation must be configured for the Moving Boundary solver. The generated
    MovingBoundarySetup XML can be consumed by the vcell-mbsolver package (``MovingBoundarySolver.from_xml``).

    Args:
        vcml_content (str): VCML content
        simulation_name (str): simulation name (must use the Moving Boundary solver)
        output_dir_path (Path): output directory path

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_moving_boundary_input(vcml_content, simulation_name, output_dir_path)
    return return_value.success, return_value.message

vcml_to_ode_input(vcml_content, simulation_name, output_dir_path)

Convert a non-spatial VCML simulation to Sundials ODE solver input (a CVODE or IDA input file)

The named simulation must be configured for CVODE, IDA or the Combined IDA/CVODE solver (Combined resolves to IDA when the math has fast systems, CVODE otherwise). The input file, with its .functions file, is written into output_dir_path and can be solved by the pyvcell-odesolver package (pyvcell_odesolver.solve(input_file, output_file)), which writes VCell's .ida results.

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
simulation_name str

simulation name (must use CVODE, IDA or Combined IDA/CVODE)

 required
output_dir_path Path

output directory path

 required

A rule-based application (reaction rules, whose network VCell generates with BioNetGen, which libvcell does not include) is converted from the math stored in the document: the network VCell generated when the model was saved. The message then says so.

Returns:

Type Description
bool

tuple[bool, str]: the success status, and on success the input file's name (<base>.cvodeInput or
str

<base>.idaInput), followed by "; stored math (...)" when the stored math was used (file names have
tuple[bool, str]

no ;, so message.split(";")[0] is the name); on failure the error message
Source code in libvcell/solver_utils.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def vcml_to_ode_input(vcml_content: str, simulation_name: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert a non-spatial VCML simulation to Sundials ODE solver input (a CVODE or IDA input file)

    The named simulation must be configured for CVODE, IDA or the Combined IDA/CVODE solver (Combined
    resolves to IDA when the math has fast systems, CVODE otherwise). The input file, with its
    ``.functions`` file, is written into ``output_dir_path`` and can be solved by the pyvcell-odesolver
    package (``pyvcell_odesolver.solve(input_file, output_file)``), which writes VCell's ``.ida`` results.

    Args:
        vcml_content (str): VCML content
        simulation_name (str): simulation name (must use CVODE, IDA or Combined IDA/CVODE)
        output_dir_path (Path): output directory path

    A rule-based application (reaction rules, whose network VCell generates with BioNetGen, which libvcell does not
    include) is converted from the math stored in the document: the network VCell generated when the model was
    saved. The message then says so.

    Returns:
        tuple[bool, str]: the success status, and on success the input file's name (``<base>.cvodeInput`` or
        ``<base>.idaInput``), followed by ``"; stored math (...)"`` when the stored math was used (file names have
        no ``;``, so ``message.split(";")[0]`` is the name); on failure the error message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_ode_input(vcml_content, simulation_name, output_dir_path)
    return return_value.success, return_value.message

vcml_to_sbml(vcml_content, application_name, sbml_file_path, round_trip_validation)

Convert VCML content to SBML file

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
application_name str

VCell Biomodel application name

 required
sbml_file_path Path

path to resulting SBML file

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/model_utils.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def vcml_to_sbml(
    vcml_content: str, application_name: str, sbml_file_path: Path, round_trip_validation: bool
) -> tuple[bool, str]:
    """
    Convert VCML content to SBML file

    Args:
        vcml_content (str): VCML content
        application_name (str): VCell Biomodel application name
        sbml_file_path (Path): path to resulting SBML file

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_sbml(
        vcml_content=vcml_content,
        application_name=application_name,
        sbml_file_path=sbml_file_path,
        round_trip_validation=round_trip_validation,
    )
    return return_value.success, return_value.message

vcml_to_vcml(vcml_content, vcml_file_path)

Process VCML content to regenerated VCML file

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
vcml_file_path Path

path to resulting VCML file

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/model_utils.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def vcml_to_vcml(vcml_content: str, vcml_file_path: Path) -> tuple[bool, str]:
    """
    Process VCML content to regenerated VCML file

    Args:
        vcml_content (str): VCML content
        vcml_file_path (Path): path to resulting VCML file

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_vcml(vcml_content=vcml_content, vcml_file_path=vcml_file_path)
    return return_value.success, return_value.message

Modules

libvcell

MathRegeneration

Bases: BaseModel

Which applications of a document had their math regenerated, and why the others failed.

Attributes:

Name Type Description
regenerated list[str]

names of the applications whose math was regenerated, in document order.
failed dict[str, str]

application name -> reason, for each application whose math generation failed; such an application keeps the math it was stored with.
Source code in libvcell/model_utils.py 
127
128
129
130
131
132
133
134
135
136
137
class MathRegeneration(BaseModel):
    """Which applications of a document had their math regenerated, and why the others failed.

    Attributes:
        regenerated: names of the applications whose math was regenerated, in document order.
        failed: application name -> reason, for each application whose math generation failed; such an
            application keeps the math it was stored with.
    """

    regenerated: list[str]
    failed: dict[str, str]

VCellExpressionError

Bases: Exception

Raised when a VCell expression cannot be evaluated.

Attributes:

Name Type Description
error_type

the originating Java exception's simple class name (e.g. DivideByZeroException, ExpressionBindingException, ParseException, FunctionDomainException), or None.
message

the error message, or None.
Source code in libvcell/model_utils.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class VCellExpressionError(Exception):
    """Raised when a VCell expression cannot be evaluated.

    Attributes:
        error_type: the originating Java exception's simple class name (e.g. ``DivideByZeroException``,
            ``ExpressionBindingException``, ``ParseException``, ``FunctionDomainException``), or ``None``.
        message: the error message, or ``None``.
    """

    def __init__(self, error_type: str | None, message: str | None) -> None:
        self.error_type = error_type
        self.message = message
        super().__init__(f"{error_type}: {message}")

evaluate_expression(expression_infix, symbol_table)

Evaluate a native-syntax VCell infix expression against a table of symbol values.

Any symbol referenced by the expression must be present in symbol_table; extra (unreferenced) symbols are permitted and ignored.

Parameters:

Name Type Description Default
expression_infix str

native VCell infix expression string (e.g. "a + b/c")

 required
symbol_table dict[str, float]

mapping of symbol name to 64-bit float value

 required

Returns:

Name Type Description
float float

the evaluated value

Raises:

Type Description
VCellExpressionError

if the expression fails to parse, references an unsupplied symbol, fails to evaluate (e.g. division by zero, math domain error), or evaluates to a non-finite value.
Source code in libvcell/model_utils.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def evaluate_expression(expression_infix: str, symbol_table: dict[str, float]) -> float:
    """
    Evaluate a native-syntax VCell infix expression against a table of symbol values.

    Any symbol referenced by the expression must be present in ``symbol_table``; extra
    (unreferenced) symbols are permitted and ignored.

    Args:
        expression_infix (str): native VCell infix expression string (e.g. ``"a + b/c"``)
        symbol_table (dict[str, float]): mapping of symbol name to 64-bit float value

    Returns:
        float: the evaluated value

    Raises:
        VCellExpressionError: if the expression fails to parse, references an unsupplied symbol,
            fails to evaluate (e.g. division by zero, math domain error), or evaluates to a
            non-finite value.
    """
    native = VCellNativeCalls()
    result: EvalReturnValue = native.evaluate_expression(expression_infix, symbol_table)
    if not result.success or result.value is None:
        raise VCellExpressionError(result.error_type, result.message)
    return result.value

sbml_to_finite_volume_input(sbml_content, output_dir_path)

Convert SBML content to finite volume input files

Parameters:

Name Type Description Default
sbml_content str

SBML content

 required
output_dir_path Path

output directory path

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/solver_utils.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def sbml_to_finite_volume_input(sbml_content: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert SBML content to finite volume input files

    Args:
        sbml_content (str): SBML content
        output_dir_path (Path): output directory path

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.sbml_to_finite_volume_input(sbml_content, output_dir_path)
    return return_value.success, return_value.message

sbml_to_ode_input(sbml_content, output_dir_path, duration, output_time_step)

Convert a non-spatial SBML model to Sundials ODE solver input (a CVODE or IDA input file)

The model's first application is simulated from 0 to duration, saving every output_time_step, on the Combined IDA/CVODE solver. Solve the input with the pyvcell-odesolver package.

Parameters:

Name Type Description Default
sbml_content str

SBML content

 required
output_dir_path Path

output directory path

 required
duration float

end time of the simulation (positive)

 required
output_time_step float

interval between saved time points (positive)

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: the success status, and the input file's name on success or the error message
Source code in libvcell/solver_utils.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def sbml_to_ode_input(
    sbml_content: str, output_dir_path: Path, duration: float, output_time_step: float
) -> tuple[bool, str]:
    """
    Convert a non-spatial SBML model to Sundials ODE solver input (a CVODE or IDA input file)

    The model's first application is simulated from 0 to ``duration``, saving every ``output_time_step``,
    on the Combined IDA/CVODE solver. Solve the input with the pyvcell-odesolver package.

    Args:
        sbml_content (str): SBML content
        output_dir_path (Path): output directory path
        duration (float): end time of the simulation (positive)
        output_time_step (float): interval between saved time points (positive)

    Returns:
        tuple[bool, str]: the success status, and the input file's name on success or the error message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.sbml_to_ode_input(sbml_content, duration, output_time_step, output_dir_path)
    return return_value.success, return_value.message

sbml_to_vcml(sbml_content, vcml_file_path)

Convert SBML content to finite volume input files

Parameters:

Name Type Description Default
sbml_content str

SBML content

 required
vcml_file_path Path

path to resulting VCML file

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/model_utils.py 
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def sbml_to_vcml(sbml_content: str, vcml_file_path: Path) -> tuple[bool, str]:
    """
    Convert SBML content to finite volume input files

    Args:
        sbml_content (str): SBML content
        vcml_file_path (Path): path to resulting VCML file

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.sbml_to_vcml(sbml_content=sbml_content, vcml_file_path=vcml_file_path)
    return return_value.success, return_value.message

vcell_infix_to_num_expr_infix(vcell_infix)

Converts an infix string version of a VCell Native Expression, and converts it to a NumExpr compatible version

Parameters:

Name Type Description Default
vcell_infix str

the infix to convert

 required

Returns:

Type Description
tuple[bool, str, str]

tuple[bool, str, str]: A tuple containing the success status, a message, and the converted infix
Source code in libvcell/model_utils.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
def vcell_infix_to_num_expr_infix(vcell_infix: str) -> tuple[bool, str, str]:
    """
    Converts an infix string version of a VCell Native Expression, and converts it to a NumExpr compatible version

    Args:
        vcell_infix (str): the infix to convert

    Returns:
        tuple[bool, str, str]: A tuple containing the success status, a message, and the converted infix
    """
    native = VCellNativeCalls()
    target_num_expr_infix = MutableString("")
    return_value: ReturnValue = native.vcell_infix_to_num_expr_infix(vcell_infix, target_num_expr_infix)
    return return_value.success, return_value.message, target_num_expr_infix.value

vcell_infix_to_python_infix(vcell_infix)

Converts an infix string version of a VCell Native Expression, and converts it to a Python compatible version

Parameters:

Name Type Description Default
vcell_infix str

the infix to convert

 required

Returns:

Type Description
tuple[bool, str, str]

tuple[bool, str, str]: A tuple containing the success status, a message, and the converted infix
Source code in libvcell/model_utils.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def vcell_infix_to_python_infix(vcell_infix: str) -> tuple[bool, str, str]:
    """
    Converts an infix string version of a VCell Native Expression, and converts it to a Python compatible version

    Args:
        vcell_infix (str): the infix to convert

    Returns:
        tuple[bool, str, str]: A tuple containing the success status, a message, and the converted infix
    """
    native = VCellNativeCalls()
    target_python_infix = MutableString("")
    return_value: ReturnValue = native.vcell_infix_to_python_infix(vcell_infix, target_python_infix)
    return return_value.success, return_value.message, target_python_infix.value

vcml_convert_units(vcml_content, unit_system, vcml_file_path)

Rewrite a VCML document in another model unit system, converting every quantity (geometry included)

For an SBML model, import it with :func:sbml_to_vcml first; VCell imports SBML in the SBML's own units.

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
unit_system str

"vcell" (µm, µM, s; what VCell's spatial and stochastic math assumes) or "sbml" (the units VCell writes SBML in)

 required
vcml_file_path Path

path to resulting VCML file

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/model_utils.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def vcml_convert_units(vcml_content: str, unit_system: str, vcml_file_path: Path) -> tuple[bool, str]:
    """
    Rewrite a VCML document in another model unit system, converting every quantity (geometry included)

    For an SBML model, import it with :func:`sbml_to_vcml` first; VCell imports SBML in the SBML's own units.

    Args:
        vcml_content (str): VCML content
        unit_system (str): "vcell" (µm, µM, s; what VCell's spatial and stochastic math assumes) or "sbml"
            (the units VCell writes SBML in)
        vcml_file_path (Path): path to resulting VCML file

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_convert_units(
        vcml_content=vcml_content, unit_system=unit_system, vcml_file_path=vcml_file_path
    )
    return return_value.success, return_value.message

vcml_regenerate_math(vcml_content, vcml_file_path)

Regenerate the math of every application of a VCML document, as VCell does when it upgrades an old document, and write the result.

Unlike vcml_to_vcml, this forces VCell's upgrade (SimulationContext.updateAll(true)): a non-spatial application that gives no absolute structure size gets the sizes VCell's StructureSizeSolver computes from its surface-to-volume ratios and volume fractions (the model's first structure anchored at 1), written into its structure mappings. Each application is regenerated on its own, so one whose math generation fails does not stop the others.

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
vcml_file_path Path

path to resulting VCML file

 required

Returns:

Type Description
tuple[bool, str, MathRegeneration | None]

tuple[bool, str, MathRegeneration | None]: the success status (the document was read and written), a message ("Success", or the error), and on success which applications were regenerated and which failed
Source code in libvcell/model_utils.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def vcml_regenerate_math(vcml_content: str, vcml_file_path: Path) -> tuple[bool, str, MathRegeneration | None]:
    """
    Regenerate the math of every application of a VCML document, as VCell does when it upgrades an old document,
    and write the result.

    Unlike ``vcml_to_vcml``, this forces VCell's upgrade (``SimulationContext.updateAll(true)``): a non-spatial
    application that gives no absolute structure size gets the sizes VCell's ``StructureSizeSolver`` computes from
    its surface-to-volume ratios and volume fractions (the model's first structure anchored at 1), written into its
    structure mappings. Each application is regenerated on its own, so one whose math generation fails does not stop
    the others.

    Args:
        vcml_content (str): VCML content
        vcml_file_path (Path): path to resulting VCML file

    Returns:
        tuple[bool, str, MathRegeneration | None]: the success status (the document was read and written), a
            message ("Success", or the error), and on success which applications were regenerated and which failed
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_regenerate_math(vcml_content=vcml_content, vcml_file_path=vcml_file_path)
    if not return_value.success:
        return False, return_value.message, None
    return True, "Success", MathRegeneration.model_validate_json(return_value.message)

vcml_to_finite_volume_input(vcml_content, simulation_name, output_dir_path)

Convert VCML content to finite volume input files

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
simulation_name str

simulation name

 required
output_dir_path Path

output directory path

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/solver_utils.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
def vcml_to_finite_volume_input(vcml_content: str, simulation_name: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert VCML content to finite volume input files

    Args:
        vcml_content (str): VCML content
        simulation_name (str): simulation name
        output_dir_path (Path): output directory path

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_finite_volume_input(vcml_content, simulation_name, output_dir_path)
    return return_value.success, return_value.message

vcml_to_moving_boundary_input(vcml_content, simulation_name, output_dir_path)

Convert VCML content to Moving Boundary solver input (a MovingBoundarySetup XML file)

The named simulation must be configured for the Moving Boundary solver. The generated MovingBoundarySetup XML can be consumed by the vcell-mbsolver package (MovingBoundarySolver.from_xml).

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
simulation_name str

simulation name (must use the Moving Boundary solver)

 required
output_dir_path Path

output directory path

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/solver_utils.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def vcml_to_moving_boundary_input(vcml_content: str, simulation_name: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert VCML content to Moving Boundary solver input (a MovingBoundarySetup XML file)

    The named simulation must be configured for the Moving Boundary solver. The generated
    MovingBoundarySetup XML can be consumed by the vcell-mbsolver package (``MovingBoundarySolver.from_xml``).

    Args:
        vcml_content (str): VCML content
        simulation_name (str): simulation name (must use the Moving Boundary solver)
        output_dir_path (Path): output directory path

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_moving_boundary_input(vcml_content, simulation_name, output_dir_path)
    return return_value.success, return_value.message

vcml_to_ode_input(vcml_content, simulation_name, output_dir_path)

Convert a non-spatial VCML simulation to Sundials ODE solver input (a CVODE or IDA input file)

The named simulation must be configured for CVODE, IDA or the Combined IDA/CVODE solver (Combined resolves to IDA when the math has fast systems, CVODE otherwise). The input file, with its .functions file, is written into output_dir_path and can be solved by the pyvcell-odesolver package (pyvcell_odesolver.solve(input_file, output_file)), which writes VCell's .ida results.

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
simulation_name str

simulation name (must use CVODE, IDA or Combined IDA/CVODE)

 required
output_dir_path Path

output directory path

 required

A rule-based application (reaction rules, whose network VCell generates with BioNetGen, which libvcell does not include) is converted from the math stored in the document: the network VCell generated when the model was saved. The message then says so.

Returns:

Type Description
bool

tuple[bool, str]: the success status, and on success the input file's name (<base>.cvodeInput or
str

<base>.idaInput), followed by "; stored math (...)" when the stored math was used (file names have
tuple[bool, str]

no ;, so message.split(";")[0] is the name); on failure the error message
Source code in libvcell/solver_utils.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def vcml_to_ode_input(vcml_content: str, simulation_name: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert a non-spatial VCML simulation to Sundials ODE solver input (a CVODE or IDA input file)

    The named simulation must be configured for CVODE, IDA or the Combined IDA/CVODE solver (Combined
    resolves to IDA when the math has fast systems, CVODE otherwise). The input file, with its
    ``.functions`` file, is written into ``output_dir_path`` and can be solved by the pyvcell-odesolver
    package (``pyvcell_odesolver.solve(input_file, output_file)``), which writes VCell's ``.ida`` results.

    Args:
        vcml_content (str): VCML content
        simulation_name (str): simulation name (must use CVODE, IDA or Combined IDA/CVODE)
        output_dir_path (Path): output directory path

    A rule-based application (reaction rules, whose network VCell generates with BioNetGen, which libvcell does not
    include) is converted from the math stored in the document: the network VCell generated when the model was
    saved. The message then says so.

    Returns:
        tuple[bool, str]: the success status, and on success the input file's name (``<base>.cvodeInput`` or
        ``<base>.idaInput``), followed by ``"; stored math (...)"`` when the stored math was used (file names have
        no ``;``, so ``message.split(";")[0]`` is the name); on failure the error message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_ode_input(vcml_content, simulation_name, output_dir_path)
    return return_value.success, return_value.message

vcml_to_sbml(vcml_content, application_name, sbml_file_path, round_trip_validation)

Convert VCML content to SBML file

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
application_name str

VCell Biomodel application name

 required
sbml_file_path Path

path to resulting SBML file

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/model_utils.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def vcml_to_sbml(
    vcml_content: str, application_name: str, sbml_file_path: Path, round_trip_validation: bool
) -> tuple[bool, str]:
    """
    Convert VCML content to SBML file

    Args:
        vcml_content (str): VCML content
        application_name (str): VCell Biomodel application name
        sbml_file_path (Path): path to resulting SBML file

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_sbml(
        vcml_content=vcml_content,
        application_name=application_name,
        sbml_file_path=sbml_file_path,
        round_trip_validation=round_trip_validation,
    )
    return return_value.success, return_value.message

vcml_to_vcml(vcml_content, vcml_file_path)

Process VCML content to regenerated VCML file

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
vcml_file_path Path

path to resulting VCML file

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/model_utils.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def vcml_to_vcml(vcml_content: str, vcml_file_path: Path) -> tuple[bool, str]:
    """
    Process VCML content to regenerated VCML file

    Args:
        vcml_content (str): VCML content
        vcml_file_path (Path): path to resulting VCML file

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_vcml(vcml_content=vcml_content, vcml_file_path=vcml_file_path)
    return return_value.success, return_value.message

Functions

sbml_to_finite_volume_input

Convert SBML content to finite volume input files

Parameters:

Name Type Description Default
sbml_content str

SBML content

 required
output_dir_path Path

output directory path

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/solver_utils.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def sbml_to_finite_volume_input(sbml_content: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert SBML content to finite volume input files

    Args:
        sbml_content (str): SBML content
        output_dir_path (Path): output directory path

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.sbml_to_finite_volume_input(sbml_content, output_dir_path)
    return return_value.success, return_value.message

vcml_to_finite_volume_input

Convert VCML content to finite volume input files

Parameters:

Name Type Description Default
vcml_content str

VCML content

 required
simulation_name str

simulation name

 required
output_dir_path Path

output directory path

 required

Returns:

Type Description
tuple[bool, str]

tuple[bool, str]: A tuple containing the success status and a message
Source code in libvcell/solver_utils.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
def vcml_to_finite_volume_input(vcml_content: str, simulation_name: str, output_dir_path: Path) -> tuple[bool, str]:
    """
    Convert VCML content to finite volume input files

    Args:
        vcml_content (str): VCML content
        simulation_name (str): simulation name
        output_dir_path (Path): output directory path

    Returns:
        tuple[bool, str]: A tuple containing the success status and a message
    """
    native = VCellNativeCalls()
    return_value: ReturnValue = native.vcml_to_finite_volume_input(vcml_content, simulation_name, output_dir_path)
    return return_value.success, return_value.message

evaluate_expression

Evaluate a native-syntax VCell infix expression against a table of symbol values.

Any symbol referenced by the expression must be present in symbol_table; extra (unreferenced) symbols are permitted and ignored.

Parameters:

Name Type Description Default
expression_infix str

native VCell infix expression string (e.g. "a + b/c")

 required
symbol_table dict[str, float]

mapping of symbol name to 64-bit float value

 required

Returns:

Name Type Description
float float

the evaluated value

Raises:

Type Description
VCellExpressionError

if the expression fails to parse, references an unsupplied symbol, fails to evaluate (e.g. division by zero, math domain error), or evaluates to a non-finite value.
Source code in libvcell/model_utils.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def evaluate_expression(expression_infix: str, symbol_table: dict[str, float]) -> float:
    """
    Evaluate a native-syntax VCell infix expression against a table of symbol values.

    Any symbol referenced by the expression must be present in ``symbol_table``; extra
    (unreferenced) symbols are permitted and ignored.

    Args:
        expression_infix (str): native VCell infix expression string (e.g. ``"a + b/c"``)
        symbol_table (dict[str, float]): mapping of symbol name to 64-bit float value

    Returns:
        float: the evaluated value

    Raises:
        VCellExpressionError: if the expression fails to parse, references an unsupplied symbol,
            fails to evaluate (e.g. division by zero, math domain error), or evaluates to a
            non-finite value.
    """
    native = VCellNativeCalls()
    result: EvalReturnValue = native.evaluate_expression(expression_infix, symbol_table)
    if not result.success or result.value is None:
        raise VCellExpressionError(result.error_type, result.message)
    return result.value

VCellExpressionError

Bases: Exception

Raised when a VCell expression cannot be evaluated.

Attributes:

Name Type Description
error_type

the originating Java exception's simple class name (e.g. DivideByZeroException, ExpressionBindingException, ParseException, FunctionDomainException), or None.
message

the error message, or None.
Source code in libvcell/model_utils.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class VCellExpressionError(Exception):
    """Raised when a VCell expression cannot be evaluated.

    Attributes:
        error_type: the originating Java exception's simple class name (e.g. ``DivideByZeroException``,
            ``ExpressionBindingException``, ``ParseException``, ``FunctionDomainException``), or ``None``.
        message: the error message, or ``None``.
    """

    def __init__(self, error_type: str | None, message: str | None) -> None:
        self.error_type = error_type
        self.message = message
        super().__init__(f"{error_type}: {message}")