---
name: biosimulant-custom-models
title: Biosimulant Custom Models
description: Create and review custom Python, VirtualCell-style, and mixed-source Biosimulant labs with documented equations, assumptions, tests, and manual-review rules.
version: 2026.05.23
tags: [biosimulant, custom-python, virtualcell, manual-review, provenance]
audience: Claude Code, Cursor, Continue, Aider
recommended: false
---

# Biosimulant Custom Models

Use this skill for custom Python, VirtualCell-style, handcrafted, or mixed-source Biosimulant labs.

Biosimulant custom labs still need the same package contract: a `BioModule`, explicit `lab.yaml` wiring, finite runtime
outputs, meaningful visualisations, README evidence, and conservative scientific claims.

## Manual-Review Default

Handcrafted models are manual-review unless their equations, parameters, assumptions, and provenance are documented well
enough to support publication.

Do not invent source claims to make a custom model look source-backed.

If a custom lab depends on an open-source library, document the library and use it directly rather than copying or
approximating its core algorithm. Examples: use NetworkX for explicit graph algorithms, SciPy/NumPy for numerical ODEs,
RDKit for cheminformatics transforms, or a domain package when the lab's source contract depends on it.

## Audit Requirements

Inspect:

- `lab.yaml`
- `models/core/model.yaml`
- wrapper/source code
- equations and hard-coded parameters
- tests
- data files
- README
- cited references

Confirm:

- the lab belongs in the model family
- equations or algorithms are documented
- hard-coded parameters have source or assumption notes
- units/defaults are not misleading
- public inputs map to real model controls
- public outputs map to real computed quantities
- `setup()` and `advance_window()` run deterministically
- outputs are finite and non-empty
- tests validate behavior where feasible, not only imports

## Public Inputs And Outputs

Inputs must correspond to real scenario controls, boundary conditions, parameters, initial conditions, files, or tensors.
Do not expose arbitrary internal constants unless the model treats them as meaningful experimental controls.

Outputs may be biologically named only when source/equation context supports the name. Use conservative names for
ambiguous variables, such as `model_state_x` or `abstract_signal_level`.

Example mapping:

```yaml
io:
  inputs:
    - name: initial_population_size
      maps_to: core.initial_population_size
      description: Initial condition used by the documented population equation.
  outputs:
    - name: population_trajectory
      maps_to: core.population_trajectory
      description: Simulated state produced by the documented model equation.
```

## Scientific Behavior Tests

Where feasible, add tests for:

- monotonic response direction
- conservation or mass balance
- boundedness
- expected steady state
- source sample parity
- deterministic behavior under fixed seeds
- sensitivity direction for public controls

## Visuals

Good custom-model visuals include:

- scenario response timeseries
- parameter sensitivity bars
- state/summary tables
- source/assumption evidence table
- Q/A table with a clear caveat

For flat or scalar models, show baseline/sensitivity evidence instead of empty charts.

## Orphan Rules

Move a custom lab out of the publish set when it is:

- scientifically misleading
- undocumented
- nonfunctional
- impossible to test
- out of scope
- too scientifically weak to repair without replacing the model

Before moving, add a README or issue note with evidence, issue type, fixability, and recommended next action.