---
name: biosimulant-cellml
title: Biosimulant CellML Labs
description: Create and polish CellML-backed Biosimulant labs using LibCellMLBioModule, libCellML validation/codegen, and source-faithful runtime outputs.
version: 2026.05.23
tags: [biosimulant, cellml, libcellml, physiology, source-faithful]
audience: Claude Code, Cursor, Continue, Aider
recommended: false
---

# Biosimulant CellML Labs

Use this skill for CellML-backed Biosimulant labs.

Biosimulant wraps the source CellML model in a `BioModule`, wires it through `lab.yaml`, emits runtime trajectories, and
uses visualisation modules plus README evidence for publication.

## Runtime Standard

Use `biosimulant.contrib.cellml.LibCellMLBioModule` for kept CellML simulator models. Keep `.cellml` files and imports as the
scientific source of truth. This is the open-source Biosimulant CellML path: libCellML parses, validates, analyses, and
generates Python code; NumPy/SciPy run the generated ODE dynamics.

Do not use OpenCOR as an embedded runtime in v1. OpenCOR may be a future validation/fallback tool; `libCellML` is the
embeddable open-source runtime path.

Do not manually reimplement CellML equations, parameters, units, or initial values.

## Wrapper Metadata

Use subclass metadata such as:

- `_CELLML_ID`
- `_TITLE`
- `_OBSERVABLES`
- `_STATE_OUTPUT_ALIASES`
- `_PARAMETER_INPUTS`
- `_INITIAL_CONDITION_INPUTS`
- `_HEADLINE_OUTPUTS`
- `_TIME_UNIT`
- `_STATE_OUTPUT_NAME`
- `_SUMMARY_OUTPUT_NAME`

Outputs should include `state`, `summary`, `trajectory`, `variable_labels`, and selected biological state/algebraic
observables when source evidence supports their names.

## Validation

Every kept CellML lab must pass:

- parse with `libCellML.Parser`
- import resolution when imports exist
- validation with `libCellML.Validator`
- analysis with `libCellML.Analyser`
- Python code generation
- SciPy integration
- finite, non-empty outputs
- no placeholder-only structure output

Fail or orphan unresolved imports, invalid CellML, unsupported DAEs, analysis failures, codegen failures, solver failures,
and wrappers that only emit CellML structure.

## Inputs And Outputs

Public inputs may only be real CellML constants, initial conditions, boundary conditions, stimulus/protocol controls, or
documented external variables.

If no safe input exists, expose no public input and document `no_public_input_deliberate`.

For ambiguous variables:

- use source metadata/RDF labels when available
- use component and units as evidence when clear
- use conservative names like `model_state_y` when evidence is weak
- never use public labels such as `dimensionless_state_v`, `source_v`, `y_y`, or invented biological claims

Keep exact CellML component/variable labels in `variable_labels`, descriptions, and README mappings.

Example public mapping:

```yaml
io:
  inputs:
    - name: initial_membrane_voltage
      maps_to: core.initial_membrane_voltage
      description: Initial condition for CellML variable `membrane.V`.
  outputs:
    - name: membrane_voltage
      maps_to: core.membrane_voltage
      description: Membrane voltage trajectory. Source variable `membrane.V`.
```

## Visuals

Good CellML visuals include:

- selected state/algebraic trajectories
- final observable ranking
- largest-change summary
- variable label/source table
- physiology-specific Q/A card
- steady-state evidence table for flat models

Visual labels should be readable and traceable, for example `Free virus particles (source v)` when source RDF supports
that label, or `Model state y (source y)` when not.

## Orphan Rules

Move non-fixable CellML labs out of the publish set when they fail source-faithful + runnable validation. Add evidence
and recovery criteria before moving them.