Evgeny Metelkin - Featured posts

Model Formats in Systems Pharmacology. Part 1

2025-08-22T00:00:00Z

Part 1, Part 2

1. Intro

Imagine web development where every framework has its own version of HTML, CSS, and JavaScript. Git is almost useless: the project is a mix of binary files and settings hidden in a GUI. Code can't be reused: each tool has its own syntax, its own logic, and a closed project file.

Sounds like a bad alternate reality, but this is still how data storage and exchange often look in drug modeling. Tools solve similar problems, but model formats are incompatible; project structure is a "black box"; reproducibility is fragile; exchange is painful.

In this article, we propose looking at a pharmacological model as code, and at the model format as an interface between people and tools.

We'll explore:

what QSP is and the role modeling plays in pharmacology;
what makes up a QSP model and how mathematics turns into structure;
the main approaches to model description (ODE scripts, process-based DSLs, tables, visual editors);
how popular tools store projects and where collaboration breaks down;
which software engineering practices (layered architecture, testing, CI/CD, semantic diffs) can actually work in QSP;
how we can improve the situation with model formats in QSP.

2. Why QSP Matters

Today, computational biology and mathematical modeling are essential in drug development - from early preclinical experiments in a test tube to full-scale clinical trials in humans. Major pharmaceutical companies are investing heavily in this field, hiring top experts in computational biology to streamline the process and make it more effective (Industry Perspective, JPKPD, 2024; Promotional Submission of QSP, JPET, 2024).

One of the fastest-growing areas is Quantitative Systems Pharmacology (QSP). In short, QSP builds detailed mathematical models that describe how drugs interact with the human body and how biological systems respond in return (NIH QSP White Paper, 2011).

Think of the human body as a complex engineered system - full of components, feedback loops, and regulators. QSP turns this system into math: models that allow pharmacologists, engineers, and statisticians to test drug behavior virtually before moving to costly and risky experiments in the lab or clinic. Much like an aerospace engineer tests a new airplane in a simulator long before the first real flight.

How QSP Relates to Other Modeling Fields

Long before QSP became a term, modelers were already working with related approaches:

Systems Biology (SB) - models networks of molecules and cells (typically non-related to drugs or clinical endpoints).
Physiologically Based Pharmacokinetics (PBPK) - models how drugs move through organs and tissues, and eliminates from the body.
Pharmacokinetics/Pharmacodynamics (PK/PD) - links drug concentration to its therapeutic effect, typically empirically or by compartmental approach.

QSP didn't appear out of nowhere - it grew out of all three. But it raised the level of detail, scaled up from molecules to whole-body systems, and aimed to bridge the gap between mechanism and clinic.

Why Software Engineers Should Care

From a developer's perspective, QSP projects look surprisingly familiar:

there is code (equations, parameters, model structure),
there are tests (validation against clinical or experimental data),
there are versions (models evolve as new data arrives),
there are teams working together on the same project,
and there are real concerns about readability, reproducibility, and maintainability.

Drug modeling is starting to resemble software engineering but without the benefit of decades of best practices. That's why ideas like modularity, version control, open formats, and CI/CD are so relevant here.

Current Challenges

For all its promise, QSP is still far from smooth sailing. In practice, many QSP teams still run into systemic challenges.

Teamwork is hard. Models are often locked inside proprietary tools, making collaboration feel more like passing around black boxes than working on shared code.
Interpretation is tricky. Results can be meaningful to insiders, but remain opaque to biologists, clinicians, or decision-makers who actually need to use them.
Reproducibility is fragile. The same model may give slightly different results depending on the tool, environment, or even the person running it.
Standards are missing. Each group develops its own formats and workflows, so models don't travel well between teams or platforms.
Maintenance is painful. Every new dataset or scientific insight often means heavy, manual re-work of existing models.

In short, QSP has the ambition of being an "engineering discipline for pharmacology", but today it still operates with the patchiness and friction of a young science.

3. Anatomy of QSP models

In Quantitative Systems Pharmacology, the body is usually represented as a network of reactions and interactions across scales—from organs to cells to molecules. Regardless of the level of detail, most models can be broken down into a few common building blocks. If we borrow concepts from software engineering, the parallels look like this:

Concept	Modeling	Software analogy
States	Molecule concentrations, cell counts, organ volumes, biomarkers	Domain states, stored fields
Processes	Reactions, transport mechanisms, discrete events	Business logic
Parameters	Organ sizes, blood flows, interaction constants, conditions	Configuration settings
Equations	Rate laws, transport equations, empirical rules	Algorithms
Solver	ODE integrator running the system dynamics	Runtime / execution engine
Datasets	Experimental, clinical, literature data	Test data, fixtures, databases
Tasks	Dose optimization, prediction, parameter estimation, validation	Use cases, automated tests

This mapping isn't perfect, but it highlights a useful perspective: QSP models aren't just collections of equations—they're systems with states, logic, data, and tasks.

A Simple Example

To make this more concrete, let's look at an example - far smaller than what modelers deal with in practice, but enough to illustrate the key principles.

Fig 1. A toy QSP model of alcohol metabolism. This minimal example is used to illustrate model structure; real QSP models can include thousands of components and interactions.

In this example, ethanol is consumed twice (state Alc_g), absorbed into the bloodstream (Alc_b), metabolized into acetaldehyde (AcHc), and then further converted into acetate (Acet).

In ODE form, the model's core dynamics are:
$$
\begin{align}
\frac{d(Alc_g)}{dt} & = -vabs_{Alc},\\
\frac{d(Alc_b \cdot blood)}{dt} & = vabs_{Alc} - v_{ADH},\\
\frac{d(AcHc \cdot blood)}{dt} & = v_{ADH} - v_{ALDH}.
\end{align}
$$

where

$$
\begin{aligned}
vabs_{Alc} & = kabs_{Alc} \cdot Alc_g,\\
v_{ADH} & = \frac{Vmax_{ADH} \cdot Alc_b}{Km_{ADH} + Alc_b} \cdot blood,\\
v_{ALDH} & = \frac{Vmax_{ALDH} \cdot AcHc}{Km_{ALDH} + AcHc} \cdot blood.
\end{aligned}
$$

Fig 2. Demo run of the toy alcohol model. Results are illustrative and qualitative, not quantitative. Definitely not medical advice (or bartending advice).

Beyond the Core Equations

In real-world projects, the mathematical core is important but just the part of the model. A complete, reproducible modeling package also needs:

Annotations - units, explanations, and key assumptions.
Parameter sets & datasets - conditions, doses, patient characteristics, and data for calibration and validation.
Solver settings & metadata - numerical settings and project history.

Without these and other metadata, results are not reproducible, and the model cannot be properly evaluated or reused. Here, we'll keep our focus on the core structure of models rather than all the surrounding layers.

4. Popular Tools and How They Store Models

At their core, QSP models are systems of algebraic and differential equations. But the moment we try to implement such a model on a computer, things get trickier. Equations need to be expressed in a very specific way - as functions, arguments, and expressions tailored for a particular programming language or solver.

Fig 3. Example of raw scripting in Matlab. Model logic (right) and simulation script (left) live in separate files but are still entangled. The model carries redundant syntax just to satisfy MATLAB and cannot be directly reused in another language or tool. Updating the model code may result in changes in the simulation script.

To make life easier, many tools introduce their own Domain Specific Languages (DSL) or rely on macros. In essence, we're still writing ODEs, but now they are expressed in a more compact, structured form. This makes the model easier to read and sometimes separates the model description from the execution code - a small but important step toward better clarity and maintainability.

However, this approach still has its drawbacks. As models grow larger, ODE-based code becomes difficult to maintain: it resists modularization, and even small changes may require edits in multiple places or restructuring the equations themselves. On top of that, the notation is far from intuitive for biologists or pharmacologists, who tend to think in terms of reactions, metabolites, and pathways rather than ODEs.

Fig 4. Example of ODE based DSL in mrgsolve. The model is expressed as a macro-like C++ dialect, which makes it close to the solver and mathematically transparent. The syntax is tool-specific and difficult to parse or convert, limiting portability beyond mrgsolve (and partially NONMEM).

One way around this is the process-based approach describing the model in terms of processes that involve metabolites, reactions, compartments and other entities. The software then generates the ODE system automatically (e.g., from tables or a custom DSL) right before simulation. This approach reduces manual edits, enables modularity, and lowers the risk of mistakes.
The trade-off? You need to adjust your modeling mindset. The equation-level view is hidden behind generation, and you need an explicit build pipeline. Still, this method has been influential SBML is one example born from such thinking.

To make models even more approachable, some tools offer visual modeling showing the model as a map or process graph. Great for accessibility, less so for large-scale version control.

In practice, different tools offer different interaction styles. For small models, it doesn't matter much which you choose. As complexity grows, the differences become critical-impacting usability, versioning, and collaboration. For example, comparing two versions, reusing components, or organizing a modular model is often much easier in a process-based DSL than in raw ODE code.

Broadly, user–model interaction falls into these categories:

Raw scripting - Pure code in a general-purpose language (MATLAB, Julia, R, Python). Maximum flexibility, minimal standardization. Equations are coded directly; solvers may also be custom-built.
Visual modeling - The user draws diagrams, with equations and parameters hidden in annotations (e.g., SimBiology, JDesigner). Great for visualization, poor for Git diffs and mass editing.
DSL-based modeling (ODE- or process-based) - A dedicated intermediate language. Balances readability, structure, and flexibility (e.g., mrgsolve, Heta); plus separating the model layer from the execution layer.
Table-based modeling - The model is defined via series of spreadsheets. The idea is similar to a DSL but avoids the need to memorize syntax. Readable, but limited in expressing complex logic.
Mixed modeling - Combinations such as tables + DSL, or tables + diagrams, etc.

Fig 5. Example of visual modeling in SimBiology. Visual diagrams make it easier for beginners and biologists to start modeling, but serious work still requires editing mathematical details hidden in tables and formulas. The binary storage format complicates version control and collaboration, while large models quickly become cumbersome as diagrams grow too complex to manage effectively.

What Ends Up on Disk: Project Storage Formats

Beyond the way models are written (authoring approach), storage format matters, especially for collaboration, exchange, and version control. Some platforms store everything in a single file; others use multiple files in different formats. In QSP, storage formats often differ across tools and are rarely interoperable.

Broad storage format categories for QSP:

Binary formats - Not human-readable, hard to diff.
Proprietary text formats - Can be opened in a text editor, but structure is obscure and not meant for manual editing.
Structured formats - Based on open standards (XML, SBML, JSON, YAML). Easier to parse and transform.
Human-readable text - Best for Git and team workflows, but still needs a parser.

The way you write a model affects how easy it is to work with, how accessible it is for collaborators, and how reusable the code becomes. The way you store a project determines whether it is Git-friendly, easy to compare across versions, and possible to translate into other tools and formats. Both layers matter — and problems often come from confusing or conflating the two.

Fig 6. Example for process-based DSL. Code for HetaSimulator. Heta offers a solver- and scripting-independent way to describe models and works well with version control. Support modules and namespaces. However, the format is niche, less familiar to those used to ODEs, and may feel harder to adopt outside its community. Requires a specific translator for use across applications.

Tool Matrix: Authoring, Storage, and Interfaces

QSP has been steadily evolving since around 2010. Many of the tools used today originated in neighboring fields such as Systems Biology, PBPK, and PK/PD. Some of them were adapted to serve QSP needs, while others were developed from scratch.

The table below summarizes key tools in the QSP landscape. Tools are included based on three criteria:

Mentioned in QSP software reviews (i.e. QSP tools review, CPT-PSP, 2018)
Positioned as QSP tools in docs or case studies
Designed for solving dynamics, not just auxiliary tasks

Software	Interaction mode	Approach	Model/project file format	Interface	Initial scope
SimBiology	Visual, Tables	Process-based	Binary (.sbproj)	GUI, Scripting (Matlab)	SB, QSP
Raw MATLAB	Raw scripting	ODE-based	Human-readable (.m)	Scripting (Matlab)	General purpose
HetaSimulator	DSL, Tables	Process-based	Human-readable (.heta)	Scripting (Julia)	QSP
Pumas	DSL	ODE-based	Human-readable (.jl)	Scripting (Julia)	PK/PD, QSP
PK-Sim/MoBi	Tables, Visual	ODE-based	Structured (.xml, .pkml)	Scripting (R)	PBPK
IQR Tools	DSL	ODE-based	Human-readable (.txt)	Scripting (R)	PK/PD
mrgsolve	DSL	ODE-based	Human-readable (.mod)	Scripting (R)	PK/PD
DBSolve	Mixed: DSL + Tables	ODE-based	Proprietary text (.slv)	GUI	SB
Berkeley Madonna	Mixed: DSL + Tables	ODE-based, Process-based	Proprietary text (.mmd)	GUI	General purpose
SimCYP	Tables	ODE-based (*restricted)	Proprietary text (.wksz)	GUI, Scripting (R)	PBPK
GastroPlus	Tables	ODE-based (*restricted)	Binary (.gpj)	GUI	PBPK
Monolix	Mixed: DSL, Tables	ODE-based	Human-readable (.mlxtran, .txt)	GUI, Scripting (R, Python)	PK/PD
NONMEM	Mixed: DSL, Tables	ODE-based	Human-readable (.ctl, .mod)	CLI, Scripting (PsN/Pirana)	PK/PD
JDesigner	Visual	Process-based	Binary (.jdes)	GUI	SB

* restricted - limited access to the ODE structure; pre-generated for drug distribution models.

What this comparison actually tells us? Looking across tools, a few patterns stand out:

Interoperability gap. Most ecosystems define their own project and model formats; moving between them usually means partial rewrites or lossy conversions.
Authoring ≠ storage. A convenient way to write a model (visual editor, macro DSL) doesn't guarantee a format that's easy to diff, review, or translate. Many tools couple authoring and storage tightly, which locks projects to a runtime.
Opacity hurts teamwork. Binary or proprietary text bundles are hard to compare, branch, and merge; they don't play well with Git, code review, or CI.
Scaling pain. ODE-centric code scales poorly: small structural tweaks (e.g., making a volume dynamic) ripple across many equations. Visual maps don't scale either—large diagrams become navigation mazes.
Skill barrier and mental models. Biologists think in terms of reactions, metabolites, pathways; engineers and solvers consume equations. Many tools force one side to work in the other side's mental model.

For teams, this creates a mix of problems: onboarding and knowledge transfer become slower, reproducibility suffers when parts of the logic are hidden in GUIs or project files, every new dataset or mechanism increases the cost of changes, and projects gradually become locked into a single vendor's toolset.

The bigger issue isn’t the formats themselves, but the isolation of the communities that use them. QSP modeling is already demanding: you need biology, math, data, statistics. Few people have the energy to master more than one tool, so most pick one and stay there. The circle closes: groups can't share because formats don't match, and formats don't match because each tool is tuned to its own little world. The way out doesn't have to come only from research groups or pharma companies—software developers can play a big role in breaking these walls too.

Next: Part 2: Engineering Practices We Can Borrow

Model Formats in Systems Pharmacology. Part 2

2025-09-06T00:00:00Z

Part 1, Part 2

In Part 1, we looked at the landscape of QSP model formats-their origins, strengths, and limitations. In this follow-up, I want to step back and explore the problem from a software engineering perspective: what practices and design principles could make QSP modeling more transparent, modular, and reproducible, and how model formats can evolve to support that shift.

5. Model as code

In software, the "X as code" idea has proven itself many times over: Infrastructure as Code (Terraform), Configuration as Code (Ansible), and Pipeline as Code (Jenkins), among others. The core idea is simple: we don't just manage artifacts (infrastructure, configuration, pipelines) directly, we manage their textual representation under version control, even if those artifacts were never treated as "code" before. In all cases, the authoritative source (canonical source for other forms) is human-readable text. This doesn't exclude working with diagrams or tables-authoring can stay visual or interactive, but the canonical format must still be code. This shift brought massive gains in transparency, modularity, and reproducibility, and accelerated progress in software engineering.

If we look back at the popular formats discussed earlier, not all of them can be considered model as code. Some are well-suited; others are not. QSP formats that are stored in binary or tool-specific project files cannot be treated as code. Formats that are formally "text-based" but too complex or unstructured for a human to read or write also only partially fit this concept.

When this principle is in place, modelers gain access to an entire ecosystem of tools: version control, diff and merge utilities, code completion, automated testing, and CI/CD pipelines. Nothing needs to be reinvented-these are the same practices that software engineers already use. It means versioned, testable, modular, and reusable models.

In practice, a model becomes more than a loose collection of files: it turns into a full engineering project with a clear folder structure, documentation, and automation. This approach improves reproducibility, makes validation and review more systematic, and simplifies onboarding new team members.

Code Transparency

Code transparency means that every aspect of a model is visible, reviewable, and understandable at a glance. This covers not only the model structure, but also the equations, parameters, and the assumptions embedded within it. A transparent format allows collaborators to see what exactly the model does without needing the original author or a proprietary tool to "explain" it.

A second requirement is traceable change. This is not only about being able to read the code, but also about being able to see what changed and why between versions. With text-based formats, differences are captured by standard tools (e.g., Git diff), making version control, peer review, and collaboration far more effective.

Fig. 1. Traceable change for NONMEM model file. Files comparison in VSCode: old vs. new. Can see changes clearly.

A desirable (not strictly mandatory) requirement is self-explanatory code. This means that the model description carries enough context-through clear naming, annotations, and units-that a new reader can understand the intent without constantly referring back to external notes or publications.

Fig. 2. Self-explanatory code trace in Antimony modeling language. File comparison in VSCode: old vs. new. Model diff meaning easy to understand at a glance because of clear syntax.

By contrast, QSP environments that store models in binary, closed, or otherwise non-readable formats cannot ensure transparency. They block the very practices-review, versioning, collaboration-that modern scientific software relies on. Even when dedicated comparison tools exist, they are typically ad-hoc, tied to a single platform, and rarely integrate smoothly into a team's normal project workflow. As a result, they are used sporadically and do not replace true text-level transparency.

Fig. 3. Non traceable change for SimBiology project (.sbproj). File comparison in VSCode: old vs. new. Model change cannot be tracked because of binary format.

Modularity

Modularity is the ability to divide a project into independent parts that can be developed, tested, and reused separately. It comes from having clear interfaces and well-defined dependencies between components.

Here we use the term broadly. It includes both the separation of different project layers: model, data, scripts (covered in more detail in the "Separation of Concerns" section), and the internal modularization of the model itself into subcomponents that are easier to manage and understand.

What modularity brings:

Code reuse. Modules can be packaged and reused across projects or systems, avoiding copy-paste and enabling larger blocks to become shared dependencies.
Clarity and maintainability. Smaller, self-contained pieces are easier to read, document, and hand over to new collaborators.
Scalability. Adding a new drug, pathway, or dataset means extending the project with a module rather than rewriting existing code.
Experimentation and flexibility. Alternative implementations (e.g., two different PK models) can be swapped or compared without touching the rest of the system.

The more logically a QSP platform is divided into modules, the easier it becomes to manage the work and distribute responsibilities. A single monolithic file forces the entire team to work sequentially, rather than in parallel.

Longevity

Longevity means that a model remains usable and trustworthy years after it was first created. Instead of "remembering which buttons we clicked," the project can be rebuilt, rerun, and revalidated from its source (FAIR Principles, Scientific Data, 2016).

Fig. 4. Git commit history in QSP project.: Commit history provides a timeline of changes in branches, enabling easy rollback and review.

What makes longevity possible:

Version history. With Git or similar systems, projects can be saved as a sequence of working snapshots. Each commit captures the state of parameters, equations, and scenarios at a given moment, creating a project timeline that can be revisited or rolled back when needed.
Environment capture. Pinned dependencies and solver settings (e.g., Project.toml, requirements.txt, renv.lock) ensure the same model can be executed in the future, regardless of local updates.
Readable formats. Text-based models outlive specific tools; even if a GUI disappears, the core code can still be read, parsed, and converted.
Re-validation. As new data or regulatory requirements arise, archived models can be rerun and checked against updated knowledge.
Knowledge preservation. Annotations, comments, and documentation carry context, so understanding does not depend on the original author's memory.
Regulatory and audit needs. Long-term reproducibility is critical for submissions: teams must show exactly what model was used to support a decision at a given time (MID3 Good Practices, CPT: PSP, 2016).

Longevity turns a QSP model from a one-off experiment into a sustainable scientific asset, something that can be reliably shared, revisited, and built upon.

Automation

Automation means that models are executed and tested through scripts instead of manual clicks. Once a model is code, it can be integrated into pipelines that ensure consistent, repeatable runs for testing, simulations, parameter estimation, or sensitivity analyses.

With CI/CD, every commit can automatically launch validation tasks, generate reports, or even dispatch heavy computations to a more powerful server or cluster (Continuous Delivery, Addison-Wesley, 2010). This reduces human error, scales effortlessly, and makes QSP projects more reliable and collaborative.

LLM & AI

When models are stored as readable code, they become accessible not only to people but also to AI assistants. This opens new opportunities for collaboration between modelers and Large Language Models.

Fig.5. Autocompletion for Heta code. GitHub Copilot can assist with code suggestions and completions if the model has unified and clear structure. Red arrow points to the AI generated suggestion.

Assisted modeling. Existing tools like GitHub Copilot or Cursor can already be used with QSP models stored as code-offering chat-based assistance, code generation, or autocompletion in Domain-Specific Language (DSL)/Macros/JSON, just as they do today for Python or R scripts.
Report integration. Because the model is code, the model updates and results can be automatically pulled into human-readable reports, presentations, or dashboards. LLMs can help generate narratives that explain changes, assumptions, or results based on the current model state.
Model as knowledge base. A structured repository can serve as a living knowledge base for LLMs. By indexing models and metadata, teams can query them conversationally ("how is clearance modeled here?") or connect them with external literature for reasoning.
Automated generation. Beyond code completion, LLMs could be used to generate entire model fragments or even full models from structured descriptions, project specifications, or natural-language prompts. For example, a developer might design a tool that takes a pathway description or a clinical protocol and produces a ready-to-run QSP model.

Used carefully--with validation, tests, and human review--AI support can turn QSP models into more interactive, transparent, and productive assets, while preserving scientific rigor.

By contrast, if the model exists only as a binary project and the GUI is the only interface, none of these benefits are available: assistants cannot read or suggest code, generation and reporting are manual, and the project remains a closed box.

6. Separation of Concerns

Separation of Concerns is a principle borrowed from software engineering. Applied to QSP, it means treating each aspect of a project as its own layer with clear boundaries and contracts. The model is not the data. The runtime is not the source. When these lines blur, projects become harder to read, validate, and reuse. When they are explicit, projects stay modular, and easier to evolve.

Layers (at a glance):

Model - description of system, biological processes: structure, equations, annotation.
Scenarios - experiment conditions: dosing, schedules, observables, simulation horizons, parameter variations.
Data - experimental/clinical datasets, raw or statistical data.
Tasks - computational actions (simulate/fit/sensitivity/identifiability) referencing Model/Scenarios/Data.
Solver config & Environment - numerical settings plus lockfiles/containers (library and OS versions).
Runtime/Engines - applications, solvers and interfaces.
Pipelines & Notebooks - automation (CLI/CI/CD) and interactive analysis (Jupyter/Quarto).
Results/Reports - outputs, logs, and report artifacts (generated by pipelines; not hand-edited).
Docs/Metadata - general annotations, assumptions, references, ontologies.

This is a fairly fine-grained breakdown for illustration. In real projects, separation can take different forms: dedicated folders, individual files, or clear structural sections inside one file in some cases. The key is that layers stay distinct, not mixed.

Another point is that each layer carries its own logic and conventions. A sensitivity-analysis script has very different requirements than a model structure. Automation may rely on technologies with its own style of configuration. Forcing everything into a monolithic structure only makes projects fragile.

The idea is familiar from software engineering: web applications separate frontend, backend, and database; frameworks use MVC or MVVM patterns. QSP projects benefit from the same discipline: each layer does its job, connected by explicit interfaces rather than hidden assumptions.

Project Structure

A practical way to implement "Separation of Concerns" is through a clear and consistent project structure. When each layer has its own dedicated place, the project becomes easier to navigate, test, and extend. In other words, the folder layout itself enforces modularity and discipline:

qsp-project/
  model/          # core structure: states, reactions, equations
  data/           # measurements for calibration/validation
  scenarios/      # description of experimental conditions and parameters
  docs/           # General purpose annotations, assumptions for the whole project
  results/        # outputs, logs, reports (generated, not hand-edited)
  julia/          # Julia code for simulation and analysis
  R/              # R code for simulation and analysis
  project.yml     # machine-readable top-level metadata, dependencies, configuration
  README.txt      # human-readable overview and instructions

Such a layout makes a QSP project behave like any other modern software repository: modular, reviewable, and easy to share. The exact structure may vary depending on how well the project can be split into layers, which tools are in use, and the team's workflow. The key is not the specific folder names, but that the structure is consistent, agreed upon, and understood by everyone on the team. This shared and long-term convention reduces friction, improves collaboration, and ensures that new members can quickly find their way around the project.

These additional principles make project structures more robust:

Keep the repository clean. The project folder should only contain what is essential: model code, data, scenarios, tasks, configuration, and documentation. Avoid bundling software installers, outdated model versions, or random drafts and unused scripts. Such clutter makes navigation harder and undermines clarity. Version control (Git) and artifact registries are the right place for history and distributions.
Single source of truth. Everything required to run or reproduce the project must either be part of the repository or referenced in a reliable, long-term way. No ambiguous dependencies on "files somewhere on a laptop" or "datasets hidden in a presentation." If a script was written for the project, it should live in the project. If external data cannot be included directly, it must be referenced with a stable identifier or DOI and clear provenance. This ensures reproducibility and integrity over time.
Stable naming and references. Avoid renaming files, folders, or key identifiers without a strong reason. Frequent or unnecessary renames break links, confuse collaborators, and make version history harder to follow. Stable names act as anchors for scripts, pipelines, and external references, ensuring continuity and trust in the project's structure.
Documentation as code. Documentation should live alongside the project and evolve together with it. Assumptions, references, and instructions belong under version control, not in scattered slides or personal notes. Keeping docs close to the source makes them reviewable, traceable, and always in sync with the current state of the project.

Model Layout

Why this matters. Data scientists have long kept data in tabular, diff-friendly formats (CSV/TAB/Parquet) and code in versioned scripts (R/Julia/Matlab/Python). The persistent gap in QSP is the model layer: when a model has no canonical, human-readable source, you can't reliably diff or review changes, and you can't automate validation. Everything downstream-reproducibility, CI, and collaboration-degrades.

"Model as code" principle treats the model as a declarative artifact with its own lifecycle. The source of truth is text. GUIs, notebooks, and binaries are authoring or execution surfaces, not the canonical store. This simple rule unlocks code review, versioning, composition, and automation for the model layer exactly as it does for code and data.

Contracts: how layers talk. When the model is kept separate from the rest of the project, it needs a clear way for other layers to reference it. Scenarios, tasks, and datasets should point to model elements through explicit identifiers-states, parameters, events, or observables in namespaces-rather than by position, file order, or ad-hoc labels. These references must be validated automatically, with pipelines configured to fail fast if an ID is missing or renamed. Stability here does not mean immobility, but transparent, predictable evolution.

Modularity at the model level. A practical layout, if your tools support a DSL or modular model files, might look like this:

model/
  core.dsl          # base states/params/eqs
  pk.dsl            # PK submodule (imports core)
  pd.dsl            # PD submodule
  cell-dynamics.dsl # cell dynamics submodule
  index.dsl         # top-level file that composes/exports modules

When available, this approach has clear advantages: each file has a narrow, stable responsibility; imports and namespaces let you compose submodels cleanly; and a single index provides the surface for downstream layers to import. This makes reuse straightforward, modules can be copied or version-pinned across repositories instead of duplicating whole projects. Even if your current environment doesn't provide such modularity, aiming for stable paths, explicit IDs, and a clear separation of responsibilities will bring similar benefits and reduce churn that breaks links or history.

Tooling for the model layer. The model layer benefits from having its own basic checks, just like data or code. At minimum, tools should confirm that equations are dimensionally consistent, that all references point to something that exists, and that every state or parameter is defined only once. It helps to run quick "sanity" simulations on each update to confirm the model still produces reproducible results. These lightweight checks make errors visible early and keep the model trustworthy as it grows.

Authoring & round-trip workflow. You can build or edit a model wherever it's convenient, through a GUI, a notebook, or even a helper script. What matters is that the final result is always saved back into a clear, text-based format. That text is what goes under version control, what reviewers look at, and what other tools check for errors. This way modelers stay free to use familiar interfaces, while the project still keeps a consistent, transparent record.

Roles & Handoffs (who edits which layer)

Different specialists can work productively when boundaries are explicit.

Model Engineer (biology focused). Owns Model + Scenarios. Delivers: validated model modules, annotations, units.
Biostatistician / Data Manager (data analysis focused). Owns Data and results. Delivers: cleaned datasets with units and provenance.
Simulation Engineer (computational methods focused). Owns Tasks + Runtime + Solver config. Delivers: task specs, algorithms, tolerances, acceptance criteria.
Runtime & DevOps Engineer (automation focused). Owns Pipelines & Notebooks + Environment. Delivers: containers/lockfiles, solver configs, CI/CD configs.

Depending on the project's goals and team size, some roles may be combined, have other titles, or be unnecessary (for example, a dedicated DevOps engineer may not be required). In other cases, additional roles can emerge, such as a technical/medical writer, visualization scientist, or a platform architect/manager. These specialists may work full time, contribute periodically or only at specific stages, but in all cases, a well-structured layered project plus clear conventions makes the whole work more effective.

Anti-patterns

In software engineering, anti-patterns are recurring practices that may seem convenient but ultimately hinder maintainability, scalability, and collaboration. QSP projects face similar risks. Identifying such anti-patterns is important because it helps teams recognize fragile structures early, and avoid repeating common mistakes. Here is the examples of anti-patterns that often appear in QSP projects:

Classic Anti-Pattern	Manifestation in QSP projects	Why it's harmful
Big Ball of Mud	Entire model, data, protocols, tasks, and results stored in a single monolithic file or notebook.	No modularity, hard to review, impossible to scale or work in parallel.
Swiss Army Knife	One application tries to do everything-modeling, simulation, analysis, data management, and reporting-without clear separation of roles.	Lacks flexibility, becomes overly complex, and prevents use of specialized tools.
Copy-and-Paste Programming	Equations and parameters duplicated or hard-coded into scripts and notebooks instead of being managed in a structured model source.	Leads to inconsistencies, errors, and maintenance headaches.
Magic Numbers / Hidden Dependencies	Defaults for model structure, doses, solver tolerances, or units applied implicitly in GUIs, with no audit trail or explicit configuration.	Non-transparent, hard to reproduce, fragile under review.
Stovepipe System	A model format or tool originally designed for smaller systems or narrow use cases, stretched to large-scale systems without modularity or namespaces.	Doesn't scale, encourages hacks, and blocks extension or reuse.
Inner-Platform Effect	Forcing all roles (modelers, data scientists, analysts) into a single rigid workflow, instead of allowing different business logics and affordances.	Stifles productivity, mismatches workflows, and limits adaptability.

7. Evaluating Your Workflow

A couple of checklists is a simple way how you can check how well your current tools and workflows align with the principles of "model as code".

Mark ☑ for each practice that is true for your current workflow.

Model-as-Code Maturity Checklist

This test is not about scoring "perfect" compliance. Instead, it highlights areas where improvements may bring the biggest benefits, such as versioning, automation, or separation of layers.

☐ Text-based authoritative source. Every part of the project can be expressed in a human-readable text format (DSL/Macros/JSON/YAML).
☐ Model layer separation. The model is stored separately from data, code, and results. Model files contain only model structure, equations, parameters, and annotations.
☐ Extensibility. You can add new components, pathways, drugs, and scripts without rewriting existing code. The time you spend on this is proportional to the size of updates, not exponential.
☐ Annotated & self-explanatory. Your model includes clear names, units, and comments that explain its structure and assumptions. Annotations are machine-readable and will be preserved across tools.
☐ Tool-agnostic. You can open, edit and execute the model and other project parts using more or one tool. Or at least export/import to/from other formats without loss of information.
☐ Meaningful diffs. When a file changes, you can review and understand the difference (both technically and semantically) easily for any part of the project.
☐ Scriptable execution. You are able to run and repeat simulations, fits, tests, and analyses from the command line or scripts, not only through a GUI.
☐ Reproducible environment. Dependencies, solver versions, and configuration are pinned (e.g., lockfiles, containers).
☐ Clear structure. The project follows a consistent folder/file layout that separates model, data, tasks, and results. All members of your project understand where to find and edit each part of the project.
☐ Project conventions. Your team has agreed on conventions for naming, versioning, and structuring the project. These conventions are documented and followed consistently.

Modern Practices Checklist

This checklist helps assess how much your project or workflow utilizes modern engineering practices.

☐ Version control. The project is under Version Control Tools (Git or equivalent), with meaningful commit history.
☐ Continuous Integration & Delivery (CI/CD). Substantial change triggers automated builds or checks (e.g., GitHub Actions, GitLab CI, Jenkins).
☐ Automated reporting. Reports, figures, and logs are generated directly from code and kept in sync with model versions.
☐ Automated testing. Unit or reproducibility tests verify correctness of model components and pipelines.
☐ Automation of routine tasks. Data preprocessing, parameter fitting are scripted, not manual. Routine operations can be autocompleted or assisted by AI tools.
☐ Remote execution. Workflows can seamlessly run on HPC clusters (like SLURM) or cloud resources when needed.

Previous: Part 1: The Missing Link Between Biology and Software Engineering

Preventing System Sleep During Long Computations

2026-01-16T00:00:00Z

In scientific and engineering modeling it is very common to run computations that take hours: overnight simulations, parameter fitting, Monte Carlo experiments, or long-running machine learning jobs. You start the script, make sure everything looks fine, and walk away.

Then the operating system decides to go to sleep.

When that happens, the computation is paused or effectively stopped. In the morning you come back to an unfinished run and lost time. This is not a rare edge case - it is a very common and very frustrating failure mode when working on laptops or workstations.

Why disabling sleep globally is not a great solution

There are obvious ways to deal with this problem:

disable sleep in system settings,
run caffeinate on macOS,
enable an "awake" mode using system tools or third-party utilities.

These approaches work, but only at a very coarse level. They keep the system awake indefinitely and have no idea when your computation has actually finished. As a result, the machine may stay awake long after the job is done, wasting power and requiring manual cleanup.

In practice, this often turns into a trade-off between reliability and convenience: either risk losing the computation, or remember to manually manage system sleep every time.

The problem is better solved at the script level

A key observation is that this is not really an operating system problem, it is a scripting problem.

Your script knows exactly when the computation starts and when it ends. That means the script itself can request sleep prevention at the beginning of the run and release it as soon as the work is complete. If something goes wrong and the script exits early, it can still clean up properly.

This leads to a much more precise and reliable solution: keep the system awake only while the computation is actually running, and automatically restore normal system behavior afterward.

One idea, implemented for three languages

Based on this idea, we implemented the same solution for three languages that are commonly used in scientific and systems modeling: R, Julia, and MATLAB.

All three implementations are called NoSleep. They follow the same conceptual design and expose a very similar interface, even though the languages and ecosystems are different.

The goal was not to create three unrelated utilities, but to provide a consistent solution that works across environments often used in the same modeling workflows.

Design principles behind NoSleep

All NoSleep implementations share a few core principles:

They rely exclusively on native operating system mechanisms:
- Power Request API on Windows,
- caffeinate on macOS,
- systemd-inhibit on Linux.
No hacks, no simulated mouse movement, no background tricks.
Fully cross-platform: Windows, macOS, and Linux.
Automatic cleanup: sleep prevention is released when the computation finishes or fails.
Open source and published through standard channels.
No external runtime dependencies.

The intention is to cooperate with the operating system rather than fight it, and to keep the behavior explicit and predictable.

Using NoSleep inside your scripts

NoSleep is designed to be used directly inside your code:

You can wrap a block of code and keep the system awake only for the duration of that block.
You can manually enable and disable sleep prevention around long-running sections.
The behavior is deterministic and reproducible, which makes scripts easier to share and reuse on other machines.

Because sleep control lives inside the script, it does not depend on external tools, system settings, or manual intervention.

Cross-language framework

All three implementations of NoSleep share the same basic API design, making it easy to switch between languages while keeping the same approach to sleep prevention.

R

Repository:
https://github.com/hetalang/NoSleepR

CRAN:
https://cran.r-project.org/web/packages/NoSleepR/index.html

Installation:

install.packages("NoSleepR")
library(NoSleepR)

Simple usage:

nosleep_on() # nosleep_on(TRUE) sets display activity
  # Long computation here
nosleep_off()

Block usage:

with_nosleep({
  # Long computation here
})

Julia

Repository:
https://github.com/hetalang/NoSleep.jl

Julia Registry:
https://juliahub.com/ui/Packages/General/NoSleep

Installation:

]add NoSleep
using NoSleep

Simple usage:

nosleep_on() # nosleep_on(keep_display=true) sets display activity
  # Long computation here
nosleep_off()

Block usage:

with_nosleep() do
  # Long computation here
end

MATLAB

Repository:
https://github.com/hetalang/NoSleepMatlab

File Exchange:
https://www.mathworks.com/matlabcentral/fileexchange/183008-nosleep

Installation:
Find in File Exchange and follow instructions.

Simple usage:

import NoSleep.*
nosleep_on(); % nosleep_on(true) sets display activity
  % Long computation here
nosleep_off();

Block usage:

function myLongComputation()
    % Long computation here
end

with_nosleep(@() myLongComputation());

When NoSleep is useful, and when it isn't

NoSleep does not make your code faster, and it does not replace proper job schedulers or cluster infrastructure. It is not meant for large distributed systems or remote compute environments.

What it does is eliminate a very common and very annoying failure mode in long local computations. In practice, small tools that quietly do one thing well often end up being used far more often than expected, simply because they remove friction from everyday work.

Good Fit Is Not Enough

2026-02-21T00:00:00Z

The Illusion of Certainty

✓ The optimizer stopped without warnings.
✓ The simulated curves match the experimental data.
✓ Residuals look acceptable.
✓ A final set of parameter values is reported.
✓ Predictions are generated and plotted.

From a workflow perspective, everything seems complete. The calibration step is done, the numbers are fixed, and the model appears ready for interpretation or decision-making. It feels deterministic: one model, one parameter set, one set of predictions.

This is the point where many modeling projects move forward.

The optimizer may settle at one acceptable solution among many equivalent ones. A good fit does not prove that the parameters are well constrained by the data. The reported parameter values represent one possible explanation of the data, not necessarily a unique explanation.

The final parameter table may give a false impression of precision. What looks like certainty may, in fact, be an illusion.

Point estimates workflow. Calibration produces a stable fit and a single set of parameter values. However, without identifiability analysis, the uniqueness and robustness of this solution remain unknown.

Why Optimization Hides the Problem

Parameter estimation in nonlinear models is an inverse problem: we try to estimate parameter values from observed outcomes. In general, inverse problems do not guarantee a unique solution. Different parameter values, or different combinations of parameters, can reproduce the data equally well, or very close to it.

Parameters may be correlated, partially redundant, or only weakly influential within the range supported by the data. As a result, several distinct parameter sets can produce nearly identical fits. An optimizer will return one of them, depending on initialization, algorithmic details, and numerical tolerances.

If we report only that single solution, we implicitly assume that the parameters are well determined. But without assessing the width of the admissible region (whether a finite confidence interval exists at all) this assumption may be false. The true parameter values consistent with the data may lie far from the reported point estimate.

Because nonlinear models often contain many interacting parameters, it is rarely possible to anticipate in advance which ones are tightly constrained and which are not. Optimization alone does not answer that question.

What Is Practical Identifiability?

Practical identifiability is not about finding a single best-fit parameter set. It is about understanding the range of parameter values that are still consistent with the observed data.

Instead of asking, "What are the optimal parameters?", we ask a different questions:

How far can each parameter move before the model no longer agrees with the data?
What are the extreme parameter values that still provide an acceptable fit?
What are the limits of the admissible parameter space?

In this sense, identifiability analysis explores the geometry of the admissible parameter space. For each parameter, it reveals whether a finite confidence interval exists, how wide it is, and whether it remains bounded or extends indefinitely. A parameter is considered practically identifiable if its admissible region is compact and well constrained by the data.

Beyond individual intervals, identifiability analysis also exposes correlations and compensatory relationships between parameters. Directions in parameter space where changes can offset each other without degrading the fit.

Importantly, these properties reflect the structure of the data-model combination. They are far less dependent on the specific optimization algorithm or on which local minimum was found. Identifiability analysis characterizes the landscape around solutions, not just a single point.

What Does Identifiability Analysis Give Us?

Once identifiability analysis is performed, the model stops being just a calibrated object and becomes a quantified one.

If all parameters turn out to be practically identifiable - meaning their confidence intervals are finite and reasonably compact - this tells us:

The available data constrain the parameters sufficiently.
The chosen parametrization is appropriate.
The calibration result is stable, not accidental.
Predictions derived from the model can be accompanied by meaningful uncertainty bounds.

This is the best-case scenario. It does not mean the model is "true" but it means the parameter estimates are genuinely supported by the data.

If some parameters are weakly identifiable or non-identifiable, the analysis still provides actionable information. Several strategies become available:

Fix and document poorly identifiable parameters, reducing the model to a reliably constrained core.
Reparametrize or group parameters, replacing unstable individual quantities with more robust composite ones.
Augment the data, either by incorporating information from the literature or by designing additional experiments.
Use model-driven experimental design, targeting conditions that improve identifiability.
Assess impact on predictions, determining whether weakly identifiable parameters actually influence the outputs of interest.

In any case, identifiability analysis eliminates false confidence. It clarifies what is supported by data and what is not, reducing the risk of unpleasant surprises when predictions fail.

Despite being conceptually well established, identifiability analysis is still not routinely included in many modeling workflows. Time pressure, computational cost, and lack of accessible tools often push it aside in practice.

Identifiability-aware workflow. By estimating parameter confidence intervals and propagating uncertainty to model outputs, we distinguish well-identified parameters from weakly identifiable ones. This leads to prediction bands that are narrow where the data constrain the model and wide where they do not.

Fisher Information Matrix and Its Limitations

A widely used approach to assessing identifiability is the Fisher Information Matrix (FIM). It evaluates local sensitivity of the model output to parameter changes near the optimum and is often available as part of standard maximum likelihood estimation. Because it is computationally efficient, it is commonly used as a quick diagnostic of parameter identifiability.

However, the FIM is inherently local. It relies on a quadratic approximation of the likelihood surface around the optimum and may not capture flat directions, strong nonlinearities, or extended regions of near-equivalent solutions. As a result, it can miss important aspects of parameter uncertainty in complex nonlinear models.

To overcome these limitations, likelihood-based methods that explore the objective function beyond the immediate neighborhood of the optimum provide a more informative assessment. By examining how far parameters can vary while maintaining agreement with the data, these approaches offer a more complete view of practical identifiability.

Profile Likelihood Methods

Likelihood-based approaches provide a principled way to assess practical identifiability. Instead of relying on local curvature near the optimum, they examine how the objective function changes as individual parameters are systematically varied. This reveals whether confidence intervals are finite and how strongly parameters are constrained by the data.

In practice, these methods are more computationally demanding and require careful implementation, which has limited their routine use in many modeling workflows.

To make such analyses more accessible, we developed an open-source Julia package, LikelihoodProfiler.jl. It implements several profile-likelihood strategies within a unified workflow, including optimization-based, integration-based, and constrained-optimization (CICO) approaches. A detailed description of the methodology and software is available in our recent JOSS publication (https://doi.org/10.21105/joss.09501).

Profile likelihood examples generated with LikelihoodProfiler.jl. By tracing the objective function beyond the optimum, these profiles expose the curvature and extent of the admissible parameter region. The threshold crossing determines finite or non-finite confidence intervals.

Conclusion: A Shift in Mindset

Nonlinear modeling is inherently challenging, especially when it involves solving inverse problems and estimating multiple interacting parameters. Once a model fits the data well, there is a natural temptation to move directly to interpretation and prediction.

However, optimal parameter values represent only part of the information contained in the data. Identifiability analysis reveals how strongly those values are supported and what constraints the data truly impose on the model. This distinction is essential for building trust in model-based conclusions and for making informed decisions.

Importantly, even weakly identifiable parameters do not automatically invalidate a model. When handled carefully, models with partial ambiguity can still provide useful insights. The key is to understand what is well constrained and what is not.

Today, practical tools make it possible to include identifiability analysis as a routine part of the modeling workflow rather than an afterthought.

Landscape of ODE Solvers in R

2026-05-04T00:00:00Z

Solving ordinary differential equations (ODEs) is a common task in many fields, including systems biology, pharmacometrics, physics, and engineering where dynamic systems are studied. An ODE describes how a variables evolve over time, typically written as
$$
\begin{align}
\frac{dx_1}{dt} & = f_1\left(t, x_1, x_2, \ldots \right), \\
\frac{dx_2}{dt} & = f_2\left(t, x_1, x_2, \ldots \right), \\
\vdots & \\
\end{align}
$$

The R ecosystem offers a collection of tools for this purpose: from lightweight numerical solvers to full modeling frameworks. This article provides a practical overview of ODE solvers in R, with a focus on helping users navigate the ecosystem and choose appropriate tools.

All packages included here were tested with simple examples and the code is available in the GitHub repository.

What is included

We include R packages that:

Support solving general ODE systems
Are mentioned in literature, documentation, or community discussions

We intentionally exclude:

Deprecated or archived packages
Thin wrappers around other frameworks without original solvers or formats
Small helper packages
Proprietary tools with limited public documentation

Some tools included in this review go beyond ODE solving and provide additional capabilities such as parameter estimation or simulation workflows. We include them for completeness, without going into those advanced features.

Packages overview table

Package	Engine	Solver type	Algorithms	Model format	Stiff	DAE	DDE	Time events	Conditional events	Downloads (2025)
deSolve	ODEPACK; DASPK (Fortran)	Compiled	lsoda, lsode, lsodes, lsodar, vode, daspk, bdf, adams, euler, rk4, ode23, ode45,	R func (interpreted); C/C++/Fortran (compiled)	Yes (lsoda)	Yes (daspk)	Yes (dede)	Yes	Yes (root finding)	635628
diffeqr	DifferentialEquations.jl SciML ecosystem	External runtime (Julia)	> 200 algorithms see docs	R func (interpreted); Julia func (JIT/compiled)	Yes	Yes	Yes	Yes	Yes (root finding)	4688
dMod	deSolve	Compiled	depends on deSolve	DSL (cOde, compiled), API (compiled)	Yes	-	-	-	-	4947
EpiModel	deSolve	Compiled	depends on deSolve	R func (interpreted)	Yes	-	Yes (dede)	-	-	23088
* IQRTools	CVODES (SUNDIALS) (C)	Compiled	BDF, Adams	DSL (Compiled)	Yes (BDF)	-	-	Yes	-	NA
mrgsolve	DLSODA (C++ translation)	Compiled	lsoda	DSL (C++-like, compiled)	Yes	-	-	Yes	-	33544
odin	deSolve	Compiled	depends on deSolve	DSL (R-like, compiled)	Yes	-	Yes (dede)	-	-	17252
PBSddesolve	solv95 (C)	Compiled	dde	R func (interpreted)	-	-	Yes	-	-	10341
PKPDsim	Boost::odeint (C++)	Compiled	Adaptive RK (RKCK54)	DSL (compiled)	-	-	-	Yes	-	10319
pracma	Matlab-inspired implementation	Pure R	ode23, ode23s, ode45, ode78	R func (interpreted)	Yes (ode23s)	-	-	-	-	1059146
r2sundials	SUNDIALS (C)	Compiled	BDF, Adams	R func (interpreted); C++ (compiled)	Yes	Yes (via IDA)	-	-	Yes (root finding)	3439
reticulate	SciPy solve_ivp (Python)	External runtime (Python)	RK45, RK23, DOP853, Radau, BDF, LSODA	R func (interpreted); Python func (interpreted)	Yes	-	-	-	Yes (root detection only)	3566483
rodeo	deSolve	Compiled	depends on deSolve	Table format (interpreted / compiled)	Yes	-	-	Yes	Yes (root finding)	3386
rstan	Stan Math Library (C++)	Compiled	rk45, bdf, adams, ckrk	DSL (Stan language, compiled)	Yes (bdf)	Yes (limited, index-1)	-	-	-	1107167
rxode2	LIBLSODA + custom (C)	Compiled	liblsoda, lsoda, dop853, indLin	DSL (R-like, compiled)	Yes	-	-	Yes	-	42872
sundialr	SUNDIALS (C)	Compiled	BDF, Adams	R func (interpreted); C++ (compiled)	Yes	Yes (via IDA)	-	Yes	-	2024

* IQRTools is proprietary; version 99.0.0 is available under AGPL-3.0 and was used in this review.

Engine

This refers to the underlying numerical implementation used by the package. This can be:

a well-known external library (e.g., ODEPACK)
a custom compiled implementation
another R package
or an external runtime (e.g., another language)

Solver type

Pure R solvers: Numerical algorithms implemented directly in R. These are easy to inspect and flexible, but typically slower due to interpreter overhead.
Compiled solvers: Implemented in C/C++/Fortran or wrapping established libraries (e.g., ODEPACK). These provide significantly better performance and are the default choice for most applications.
External runtime interfaces: Packages that delegate computation to external ecosystems such as Julia or Python. These act as bridges rather than standalone solvers.

Algorithms

This is the list of available numerical methods as documented by the package.

Model format

ODE models can be defined in different ways: as R functions, domain-specific languages (DSL), structured APIs, or even external code.

The key distinction affecting performance is how the model is executed:

Interpreted execution: The model is defined as an R function and evaluated during each solver step.
Compiled execution: The model is translated into compiled code before simulation, avoiding interpreter overhead and improving performance.

Stiff

Indicates whether the solver can handle stiff systems. Stiffness arises when a system contains processes evolving on very different time scales. Solvers that support stiffness typically use implicit methods or adaptive switching (e.g., LSODA).

DAE / DDE

Support for these features is solver-dependent and often requires specific algorithms.

DAE (Differential-Algebraic Equations): Systems that include algebraic constraints in addition to differential equations.
DDE (Delay Differential Equations): Systems where derivatives depend on past states.

Time events / Conditional events

These features are important for modeling real-world systems with discontinuities.

Time events: Discrete changes applied at predefined time points (e.g., dosing events).
Conditional events: Events triggered when a condition is met during simulation (e.g., threshold crossing).

Downloads 2025

Total number of downloads in 2025 from CRAN, reflecting usage statistics. Calculated with CRAN logs.

Repository and test cases

To ensure practical consistency, packages were tested on two simple ODE models. The full code for all packages is available in the companion GitHub repository.

We are providing here the code in mrgsolve format for two examples: a pharmacokinetic model with non-linear elimination, and the Robertson problem, which is a classic stiff ODE system.

Example 1: Pharmacokinetic model with non-linear elimination

library(mrgsolve)
library(magrittr)

# load model as DLS (C++ like)
mod <- mcode("pk_model", '
$PARAM
kabs_Alc = 10.0
Vmax_ADH = 3
Km_ADH = 0.1
V_blood = 5.5

$CMT
Alc_g Alc_b_amt

$ODE
double Alc_b = Alc_b_amt / V_blood;
double vabs_Alc = kabs_Alc * Alc_g;
double v_ADH = Vmax_ADH * Alc_b / (Km_ADH + Alc_b) * V_blood;

dxdt_Alc_g = -vabs_Alc;
dxdt_Alc_b_amt = vabs_Alc - v_ADH;

$TABLE
capture Alc_b;
')

# time event
ev1 <- ev(time = 2, amt = 50, cmt = "Alc_g")

# solve
out <- mod %>%
  init(Alc_g = 50, Alc_b_amt = 0) %>%
  ev(ev1) %>%
  mrgsim(start = 0, end = 12, delta = 0.001)

plot(out)

Example 2: Robertson problem stiff ODE

library(mrgsolve)
library(magrittr)

# load model as DLS (C++ like)
mod <- mcode("rob_model", '
$CMT
A B C

$ODE
dxdt_A = -0.04 * A + 1e4 * B * C;
dxdt_B =  0.04 * A - 1e4 * B * C - 3e7 * pow(B, 2);
dxdt_C =  3e7 * pow(B, 2);
')

# solve
out <- mod %>%
  init(A = 1, B = 0, C = 0) %>%
  mrgsim(start = 0, end = 1, delta = 1e-2)

plot(out)

Author's notes

The goal of this review was to provide a maximally complete and objective overview of tools for solving ODEs in R. The packages included in this survey differ in their purpose and functionality: from simple numerical solvers to full-featured frameworks and specialized domain-specific tools. Many aspects, such as computational performance, numerical accuracy, and advanced functionality are intentionally not covered in this article.

Many packages designed for specific application areas (e.g., PK/PD) can also be used to solve general ODE systems. These are included here on equal footing, without focusing on their domain-specific features.

Due to the nature of the R ecosystem, most tools that could be systematically reviewed, tested, and compared in a reproducible way are open-source packages. While several proprietary engines also provide ODE-solving capabilities, their internal implementations, numerical methods, and usage are not always publicly documented or accessible without licenses. As a result, they are not included in the main comparison table.

For a broader overview, see the CRAN Task View: Differential Equations.

Download metrics

The table includes popularity metrics as download counts. However, these numbers do not reflect the actual capabilities of the packages. Downloads may include one-time installations for educational purposes, CI/CD workflows, or usage of a package for non-ODE problems. Therefore, they should not be considered a deciding factor when choosing a tool, but rather as a rough indicator of visibility within the community.

deSolve

deSolve is one of the most widely used and established ODE packages in R. Its central role in the ecosystem is reflected not only in its large user base, but also in the number of other packages that build on top of it.

It provides a broad set of numerical methods and supports a wide range of problem types, including stiff systems, DAEs, DDEs, and event handling. At the same time, it offers flexible model definitions, from simple R functions to compiled code.

Overall, deSolve can be seen as a foundational tool in the R ecosystem for differential equations. Its popularity is well justified by its versatility, stability, and long-term development. If you are new to ODE modeling in R, starting with deSolve is a safe and practical choice before exploring more specialized tools.

Model formats

An important factor when choosing a tool is the model definition format. The R ecosystem offers a wide range of approaches: from simple R functions (deSolve, pracma, PBSddesolve) and tabular specifications (rodeo) to domain-specific languages (PKPDsim, rstan) and low-level compiled code (rxode2, mrgsolve, deSolve).

These differences affect both performance and usability, and often determine how easily a model can be developed, modified, and integrated into a workflow.

Limitations and gaps

Despite the variety of available tools, support for some important features remains limited across the R ecosystem. In particular, capabilities such as delay differential equations (DDE), differential-algebraic equations (DAE), and advanced event handling are only partially implemented and are available in relatively few packages. As a result, modeling tasks that rely on these capabilities may require additional effort, careful selection of tools, or even custom implementations.

Disclaimer

This article will be continuously updated. If you find any inaccuracies or have suggestions, feel free to open an issue:
https://github.com/metelkin/ode-solvers-in-r/issues