gotranx 2.2.0__tar.gz → 2.3.0__tar.gz

{gotranx-2.2.0/src/gotranx.egg-info → gotranx-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gotranx
-Version: 2.2.0
+Version: 2.3.0
 Summary: A declarative language describing ordinary differential equations
 Author-email: Henrik Finsberg <henriknf@simula.no>
 License: MIT
@@ -116,7 +116,12 @@ with the initial conditions $x(0) = 1$ and $y(0) = 0$ and the parameter $a$ with
 ```
 gotranx ode2py file.ode --scheme explicit_euler -o file.py
 ```
-which will create a file `file.py` containing functions for solving the ODE. Now you can solve the ode using the following code snippet
+which will create a file `file.py` containing functions for solving the ODE.
+The same ODE can be turned into C (`ode2c`), Julia (`ode2julia`), a
+ModelingToolkit system (`ode2mtk`), UFL (`ode2ufl`), Markdown (`ode2md`),
+CellML (`ode2cellml`) or a [CytoZoo](https://github.com/finsberg/CytoZoo.jl)
+cell-model adapter (`ode2cytozoo` -- whose output needs a CytoZoo providing
+`resolve_parameter`, not yet released). Now you can solve the ode using the following code snippet
 
 ```python
 import file as model

{gotranx-2.2.0 → gotranx-2.3.0}/README.md

@@ -57,7 +57,12 @@ with the initial conditions $x(0) = 1$ and $y(0) = 0$ and the parameter $a$ with
 ```
 gotranx ode2py file.ode --scheme explicit_euler -o file.py
 ```
-which will create a file `file.py` containing functions for solving the ODE. Now you can solve the ode using the following code snippet
+which will create a file `file.py` containing functions for solving the ODE.
+The same ODE can be turned into C (`ode2c`), Julia (`ode2julia`), a
+ModelingToolkit system (`ode2mtk`), UFL (`ode2ufl`), Markdown (`ode2md`),
+CellML (`ode2cellml`) or a [CytoZoo](https://github.com/finsberg/CytoZoo.jl)
+cell-model adapter (`ode2cytozoo` -- whose output needs a CytoZoo providing
+`resolve_parameter`, not yet released). Now you can solve the ode using the following code snippet
 
 ```python
 import file as model

{gotranx-2.2.0 → gotranx-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gotranx"
-version = "2.2.0"
+version = "2.3.0"
 description = "A declarative language describing ordinary differential equations"
 authors = [{name = "Henrik Finsberg", email = "henriknf@simula.no"}]
 license = {text = "MIT"}
@@ -172,7 +172,7 @@ tag = true
 sign_tags = false
 tag_name = "v{new_version}"
 tag_message = "Bump version: {current_version} → {new_version}"
-current_version = "2.2.0"
+current_version = "2.3.0"
 
 
 [[tool.bumpversion.files]]

{gotranx-2.2.0 → gotranx-2.3.0}/src/gotranx/cli/__init__.py

@@ -8,7 +8,7 @@ import typer
 from ..schemes import Scheme, get_scheme
 from ..codegen import PythonFormat, CFormat
 from ..codegen.base import Shape
-from . import gotran2c, gotran2py, gotran2julia, gotran2md, gotran2mtk, gotran2ufl
+from . import gotran2c, gotran2py, gotran2julia, gotran2cytozoo, gotran2md, gotran2mtk, gotran2ufl
 from . import utils
 
 app = typer.Typer()
@@ -659,6 +659,70 @@ def ode2julia(
     )
 
 
+@app.command()
+def ode2cytozoo(
+    fname: typing.Optional[Path] = typer.Argument(
+        None, exists=True, file_okay=True, dir_okay=False, readable=True, resolve_path=True
+    ),
+    outname: typing.Optional[str] = typer.Option(None, "-o", "--outname", help="Output name"),
+    model_name: typing.Optional[str] = typer.Option(
+        None, "--model-name", help="Julia struct name (default: the ODE name in PascalCase)"
+    ),
+    v_name: str = typer.Option("v", "--v-name", help="State holding the transmembrane potential"),
+    remove_unused: bool = typer.Option(False, "--remove-unused", help="Remove unused variables"),
+    remove_singularities: bool = typer.Option(
+        True,
+        "--remove-singularities/--no-remove-singularities",
+        help=(
+            "Replace a small neighborhood of every removable singularity "
+            "(e.g. x/(exp(x) - 1) at x = 0) with a truncated Taylor series"
+        ),
+    ),
+    version: bool = typer.Option(
+        None,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version",
+    ),
+    license: bool = typer.Option(
+        None,
+        "--license",
+        callback=license_callback,
+        is_eager=True,
+        help="Show license",
+    ),
+    config: typing.Optional[Path] = typer.Option(
+        None,
+        "-c",
+        "--config",
+        help="Read configuration options from a configuration file",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
+):
+    if fname is None:
+        return typer.echo("No file specified")
+
+    config_data = utils.read_config(config)
+    verbose = config_data.get("verbose", verbose)
+    remove_singularities = utils.validate_remove_singularities(
+        config_data.get("remove_singularities", remove_singularities)
+    )
+    cytozoo_config = config_data.get("cytozoo", {})
+    model_name = cytozoo_config.get("model_name", model_name)
+    v_name = cytozoo_config.get("v_name", v_name)
+
+    gotran2cytozoo.main(
+        fname=fname,
+        outname=outname,
+        model_name=model_name,
+        v_name=v_name,
+        remove_unused=remove_unused,
+        remove_singularities=remove_singularities,
+        verbose=verbose,
+    )
+
+
 @app.command()
 def ode2mtk(
     fname: typing.Optional[Path] = typer.Argument(

gotranx-2.3.0/src/gotranx/cli/gotran2cytozoo.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+from pathlib import Path
+import logging
+import structlog
+
+from ..codegen.cytozoo import CytoZooCodeGenerator
+from ..load import load_ode
+from ..ode import ODE
+
+logger = structlog.get_logger()
+
+
+def _banner(source: str) -> str:
+    """The provenance header every generated module carries.
+
+    Hand-written headers in the consuming repo are deleted the moment anyone runs
+    the documented regeneration command, so the generator has to emit its own.
+    """
+    # Deferred: gotranx/__init__.py imports this package, so a module-level
+    # import of __version__ would be circular.
+    from .. import __version__
+
+    return "\n".join(
+        [
+            f"# Generated by gotranx {__version__} from {source} -- do not hand-edit.",
+            "# Regenerate with `gotranx ode2cytozoo` rather than editing this file.",
+            "# Requires a CytoZoo providing `resolve_parameter`; no released CytoZoo",
+            "# has it yet, so this module needs a development checkout of CytoZoo.",
+            "# Top-level names here (`rhs`, `NUM_STATES`, ...) are unqualified, so",
+            "# loading several generated models in one session needs each wrapped in",
+            "# its own `module`.",
+        ]
+    )
+
+
+def get_code(
+    ode: ODE,
+    model_name: str | None = None,
+    v_name: str = "v",
+    remove_unused: bool = False,
+    source: Path | str | None = None,
+) -> str:
+    """Generate the CytoZoo cell-model adapter for the ODE
+
+    Parameters
+    ----------
+    ode : gotranx.ode.ODE
+        The ODE
+    model_name : str | None, optional
+        Name of the generated Julia struct, by default None, which uses the
+        ODE's own name in PascalCase. Must be a valid Julia identifier
+    v_name : str, optional
+        Name of the state holding the transmembrane potential, by default "v"
+    remove_unused : bool, optional
+        Remove unused variables, by default False
+    source : pathlib.Path | str | None, optional
+        The source `.ode` file, named in the provenance banner. Only its
+        basename is emitted, by default None, which falls back to the ODE's
+        name. An absolute path would otherwise leak one machine's layout into
+        a committed file
+
+    Returns
+    -------
+    str
+        The CytoZoo adapter code
+
+    Raises
+    ------
+    gotranx.exceptions.InvalidModelName
+        If the model name is not a valid Julia identifier
+    gotranx.exceptions.MissingPotentialState
+        If no state is named `v_name`
+    """
+    codegen = CytoZooCodeGenerator(
+        ode, model_name=model_name, v_name=v_name, remove_unused=remove_unused, type_stable=True
+    )
+
+    source_name = Path(source).name if source is not None else f"{ode.name}.ode"
+
+    comp = [
+        _banner(source_name),
+        "import CytoZoo",
+        "using CytoZoo: AbstractCardiacCellModel, SpatialContext, resolve_parameter",
+        "import CytoZoo: num_states, num_parameters, transmembrane_potential_index",
+        "import CytoZoo: default_initial_state, state_index, parameter_index",
+        "import CytoZoo: state_names, parameter_names",
+        "import CytoZoo: num_monitors, monitor_names, monitor_values!",
+        f"const NUM_STATES = {len(ode.states)};",
+        f"const NUM_PARAMS = {len(ode.parameters)};",
+        codegen.initial_parameter_values(),
+        codegen.initial_state_values(),
+        codegen.rhs(),
+        codegen.monitor_values(),
+        codegen.adapter(),
+    ]
+    return codegen._format("\n".join(comp))
+
+
+def main(
+    fname: Path,
+    outname: Path | str | None = None,
+    model_name: str | None = None,
+    v_name: str = "v",
+    remove_unused: bool = False,
+    remove_singularities: bool = True,
+    verbose: bool = False,
+) -> None:
+    loglevel = logging.DEBUG if verbose else logging.INFO
+    structlog.configure(wrapper_class=structlog.make_filtering_bound_logger(loglevel))
+    ode = load_ode(fname, remove_singularities=remove_singularities)
+    code = get_code(
+        ode,
+        model_name=model_name,
+        v_name=v_name,
+        remove_unused=remove_unused,
+        source=fname,
+    )
+    out = fname if outname is None else Path(outname)
+    out_name = out.with_suffix(suffix=".jl")
+    out_name.write_text(code)
+    logger.info(f"Wrote {out_name}")

{gotranx-2.2.0 → gotranx-2.3.0}/src/gotranx/codegen/__init__.py

@@ -10,6 +10,7 @@ from .base import CodeGenerator, Func, RHSArgument, SchemeArgument
 from .ode import GotranODECodePrinter, BaseGotranODECodePrinter
 from .julia import JuliaCodeGenerator, GotranJuliaCodePrinter
 from .mtk import MTKCodeGenerator
+from .cytozoo import CytoZooCodeGenerator, MissingPotentialState  # noqa: F401
 
 __all__ = [
     "base",
@@ -32,4 +33,6 @@ __all__ = [
     "GotranJuliaCodePrinter",
     "JaxCodeGenerator",
     "MTKCodeGenerator",
+    "CytoZooCodeGenerator",
+    "MissingPotentialState",
 ]

{gotranx-2.2.0 → gotranx-2.3.0}/src/gotranx/codegen/base.py

@@ -218,6 +218,7 @@ class CodeGenerator(abc.ABC):
             state_names=[s.name for s in self.ode.sorted_states()],
             state_values=[self.printer.doprint(s.value) for s in self.ode.sorted_states()],
             name=name,
+            **self._init_value_kwargs(),
         )
         return self._format(code)
 
@@ -247,9 +248,20 @@ class CodeGenerator(abc.ABC):
             parameter_names=[s.name for s in self.ode.parameters],
             parameter_values=[self.printer.doprint(s.value) for s in self.ode.parameters],
             name=name,
+            **self._init_value_kwargs(),
         )
         return self._format(code)
 
+    def _init_value_kwargs(self) -> dict[str, typing.Any]:
+        """Extra keyword arguments for the `init_*_values` templates.
+
+        Empty for every backend whose initial-value functions need no signature
+        of their own. The Julia backend overrides it, because under
+        `--type-stable` the emitted bodies refer to `TYPE` and so the functions
+        need a type parameter to bind it.
+        """
+        return {}
+
     def _state_assignments(self, states: sympy.IndexedBase, remove_unused: bool) -> str:
         return "\n".join(
             self._doprint(state.symbol, states[i], use_variable_prefix=True)

gotranx-2.3.0/src/gotranx/codegen/cytozoo.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import structlog
+
+from ..ode import ODE
+from .. import templates
+from .. import atoms
+from ..exceptions import InvalidModelName, MissingPotentialState
+from .base import RHSArgument
+from .julia import JuliaCodeGenerator
+
+logger = structlog.get_logger()
+
+# Both exceptions live in gotranx.exceptions alongside every other GotranxError,
+# so `except exceptions.GotranxError` catches them. They stay importable from
+# here, which is where they are raised and where callers already import them.
+__all__ = ["CytoZooCodeGenerator", "InvalidModelName", "MissingPotentialState"]
+
+
+def _pascal_case(name: str) -> str:
+    return "".join(
+        part[:1].upper() + part[1:] for part in name.replace("-", "_").split("_") if part
+    )
+
+
+class CytoZooCodeGenerator(JuliaCodeGenerator):
+    """Emit a CytoZoo cell-model adapter.
+
+    Subclasses the Julia generator so every expression, every `TYPE(...)`-wrapped
+    literal and every assignment block is shared rather than reimplemented. What
+    differs is the RHS signature (Task 5), the parameter assignments (Task 5) and
+    the adapter block below.
+    """
+
+    def __init__(
+        self,
+        ode: ODE,
+        model_name: str | None = None,
+        v_name: str = "v",
+        remove_unused: bool = False,
+        type_stable: bool = True,
+    ) -> None:
+        super().__init__(ode, remove_unused=remove_unused, type_stable=type_stable)
+        name = model_name or _pascal_case(ode.name or "Model")
+        # `_pascal_case` only splits on `-`/`_`, so an ODE named `1962_noble`,
+        # `tentusscher panfilov` or `my.model` -- and any `--model-name` the
+        # user passes -- can still start with a digit or carry a space or a
+        # dot. Each emits `struct <invalid>{T <: AbstractVector}`, a Julia
+        # parse error hundreds of lines away from its cause.
+        if not name.isidentifier():
+            raise InvalidModelName(name)
+        self._model_name = name
+        self._v_name = v_name
+
+    @property
+    def template(self):
+        return templates.julia
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
+
+    def _state_name_list(self) -> list[str]:
+        # self.ode.states is name-sorted; sorted_states() is the dependency order
+        # that fills `u`, which is what state_index()/_state_assignments() in
+        # codegen/base.py actually use (base.py:171, base.py:268). Using the
+        # name-sorted list here would silently mislabel every state slot.
+        return [s.name for s in self.ode.sorted_states()]
+
+    def _parameter_name_list(self) -> list[str]:
+        return [p.name for p in self.ode.parameters]
+
+    def _monitor_name_list(self) -> list[str]:
+        # Mirror codegen.base.CodeGenerator.monitor_index (base.py:186) exactly:
+        # one pass over sorted_assignments() in encounter order, not two
+        # name-sorted blocks concatenated. Monitor slots must match monitor_index.
+        return [
+            a.name
+            for a in self.ode.sorted_assignments(remove_unused=False)
+            if isinstance(a, (atoms.Intermediate, atoms.StateDerivative))
+        ]
+
+    def _potential_index(self) -> int:
+        names = self._state_name_list()
+        try:
+            return names.index(self._v_name) + 1
+        except ValueError:
+            raise MissingPotentialState(
+                v_name=self._v_name, ode_name=self.ode.name, state_names=names
+            ) from None
+
+    def _rhs_arguments(self, order=None, const_states: bool = True):
+        """The Julia signature plus the two spatial arguments.
+
+        `_cz_`-prefixed so an .ode declaring a parameter called `x` or `overrides`
+        still generates valid code.
+
+        Typing the overrides follows the house pattern CytoZoo's own models use
+        (docs/src/guides/implementing_a_model.md, "Adding Spatial Support"):
+        giving them their own type parameter makes the method specialize on the
+        override NamedTuple's type, so the `Nothing` case compiles the whole
+        spatial branch away instead of leaving a runtime check behind. Julia
+        does not specialize on an untyped argument that is only passed along.
+
+        The guide spells that type parameter `F`, which cannot be used verbatim
+        here: `F` is Faraday's constant in every cardiac model, and the emitted
+        body assigns a local `F = TYPE(resolve_parameter(...))` for it, which
+        Julia rejects with "local variable name \"F\" conflicts with a static
+        parameter". The generated name is `_cz_F` for the same reason the
+        arguments are `_cz_`-prefixed, and for the same reason the element type
+        is `TYPE` rather than `T`.
+        """
+        func = super()._rhs_arguments(
+            order if order is not None else RHSArgument.tsp, const_states=const_states
+        )
+        post = func.post_function_signature
+        if post:
+            # " where {TYPE, TIME, PARAM, OUT}" -> " where {TYPE, TIME, PARAM, OUT, _cz_F}"
+            post = post.rstrip().removesuffix("}") + ", _cz_F}"
+        else:
+            post = " where {_cz_F}"
+        return func._replace(
+            arguments=list(func.arguments) + ["_cz_x", "_cz_overrides::_cz_F"],
+            post_function_signature=post,
+        )
+
+    def _parameter_assignments(self, parameters) -> str:
+        """Every parameter local resolves against the spatial overrides.
+
+        `resolve_parameter` is CytoZoo public API. It is @inline and `name in names`
+        folds against the override NamedTuple's type parameter, so a parameter with no
+        override costs nothing at runtime; the ::Nothing method returns the fallback
+        directly.
+        """
+        lines = []
+        for i, param in enumerate(self.ode.parameters):
+            if not self._condition(param.name):
+                continue
+            lines.append(
+                f"{param.name} = TYPE(resolve_parameter("
+                f"parameters[{i + 1}], _cz_overrides, Val(:{param.name}), _cz_x, t))"
+            )
+        return "\n".join(lines)
+
+    def adapter(self) -> str:
+        """The struct, name tuples, index lookups and interface methods."""
+        name = self._model_name
+        monitors = self._monitor_name_list()
+        parts = [
+            templates.cytozoo.model_struct(name, len(self.ode.parameters)),
+            templates.cytozoo.name_tuples(
+                name, self._state_name_list(), self._parameter_name_list(), monitors
+            ),
+            templates.cytozoo.index_lookups(
+                name, self._state_name_list(), self._parameter_name_list()
+            ),
+            templates.cytozoo.interface_methods(name, self._potential_index(), len(monitors)),
+        ]
+        return self._format("\n".join(parts))

{gotranx-2.2.0 → gotranx-2.3.0}/src/gotranx/codegen/julia.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+import typing
 import structlog
 from sympy.printing.julia import JuliaCodePrinter
 from sympy.codegen.ast import Assignment
@@ -73,6 +74,9 @@ class JuliaCodeGenerator(CodeGenerator):
     def template(self):
         return templates.julia
 
+    def _init_value_kwargs(self) -> dict[str, typing.Any]:
+        return {"type_stable": self._printer._type_stable}
+
     def imports(self) -> str:
         return ""
         # return self._format(
@@ -89,13 +93,19 @@ class JuliaCodeGenerator(CodeGenerator):
     ) -> Func:
         value = RHSArgument.get_value(order)
         if self._printer._type_stable:
+            # Each argument gets its OWN type parameter. Tying them to a single
+            # `TYPE` means no AD-based stiff solver in the SciML stack can call
+            # the emitted `rhs`: such a solver differentiates with respect to the
+            # states only, calling `f(du, u, p, t)` with `Dual` `u`/`du` and the
+            # original `Float64` `p` and `t`, a combination no single-parameter
+            # method matches.
             argument_dict = {
                 "s": "states::AbstractVector{TYPE}",
-                "t": "t::TYPE",
-                "p": "parameters::AbstractVector{TYPE}",
+                "t": "t::TIME",
+                "p": "parameters::AbstractVector{PARAM}",
             }
-            values = ["values::AbstractVector{TYPE}"]
-            post_function_signature = " where {TYPE}"
+            values = ["values::AbstractVector{OUT}"]
+            post_function_signature = " where {TYPE, TIME, PARAM, OUT}"
         else:
             argument_dict = {
                 "s": "states",
@@ -125,14 +135,18 @@ class JuliaCodeGenerator(CodeGenerator):
     ) -> Func:
         value = SchemeArgument.get_value(order)
         if self._printer._type_stable:
+            # Own type parameter per argument, for the reason given in
+            # `_rhs_arguments`. A stepper is called with the same mixture of
+            # differentiated states and undifferentiated parameters, time and
+            # step size.
             argument_dict = {
                 "s": "states::AbstractVector{TYPE}",
-                "t": "t::TYPE",
-                "d": "dt::TYPE",
-                "p": "parameters::AbstractVector{TYPE}",
+                "t": "t::TIME",
+                "d": "dt::DT",
+                "p": "parameters::AbstractVector{PARAM}",
             }
-            values = ["values::AbstractVector{TYPE}"]
-            post_function_signature = " where {TYPE}"
+            values = ["values::AbstractVector{OUT}"]
+            post_function_signature = " where {TYPE, TIME, DT, PARAM, OUT}"
         else:
             argument_dict = {
                 "s": "states",

{gotranx-2.2.0 → gotranx-2.3.0}/src/gotranx/exceptions.py

@@ -125,3 +125,31 @@ class ResolveExpressionError(GotranxError, ValueError):
 
     def __str__(self) -> str:
         return f"Unable to resolve expression for {self.name!r}"
+
+
+@dataclass
+class MissingPotentialState(GotranxError, ValueError):
+    v_name: str
+    ode_name: str
+    state_names: list[str]
+
+    def __str__(self) -> str:
+        return (
+            f"no state named {self.v_name!r} in ODE {self.ode_name!r}; "
+            f"pass v_name=<state> (CLI: --v-name) naming the transmembrane potential. "
+            f"States are: {', '.join(self.state_names)}"
+        )
+
+
+@dataclass
+class InvalidModelName(GotranxError, ValueError):
+    name: str
+
+    def __str__(self) -> str:
+        return (
+            f"Model name {self.name!r} is not a valid Julia identifier, so the "
+            "generated `struct` would not parse. A valid name starts with a letter "
+            "or underscore and contains only letters, digits and underscores -- "
+            "e.g. 'ORdmmLand'. Pass a different name with model_name= "
+            "(CLI: --model-name)."
+        )

{gotranx-2.2.0 → gotranx-2.3.0}/src/gotranx/templates/__init__.py

@@ -8,6 +8,7 @@ from . import julia
 from . import mtk
 from . import markdown
 from . import ufl
+from . import cytozoo
 
 
 class Template(typing.Protocol):
@@ -197,4 +198,4 @@ class Template(typing.Protocol):
         """
 
 
-__all__ = ["c", "python", "jax", "julia", "markdown", "mtk", "Template", "ufl"]
+__all__ = ["c", "python", "jax", "julia", "markdown", "mtk", "Template", "ufl", "cytozoo"]