---
title: 'PhysiBoSS-Models: Multiscale Modeling Repository'
url: https://www.emergentmind.com/topics/physiboss-models
type: topic
---

# PhysiBoSS-Models: Multiscale Modeling Repository

Searching arXiv for the cited PhysiBoSS and PhysiBench papers to ground the article in the latest literature.
{"queries":[{"query":"ti:\"PhysiBoSS-Models: A database for multiscale models\"","source":"arxiv"},{"query":"ti:\"A benchmark suite of intracellular Boolean model variants and multiscale simulations for computational biology\"","source":"arxiv"},{"query":"ti:\"Building multiscale models with PhysiBoSS, an agent-based modeling tool\"","source":"arxiv"}]}
PhysiBoSS-Models is a curated, version-controlled database of multiscale models built with the PhysiBoSS framework. In this framework, PhysiBoSS integrates an agent-based model of individual cells in space, via PhysiCell, with intracellular stochastic continuous-time Boolean networks, via MaBoSS, inside each cell. PhysiBoSS-Models was developed to promote model sharing and versioning, to provide standardized access to validated models, and to facilitate reuse, validation, and benchmarking through a simple Python API and PhysiCell Studio integration [2508.05550].

## 1. Definition, rationale, and position in the software stack

PhysiBoSS-Models addresses a recurrent problem in multiscale computational biology: models built on top of PhysiBoSS and PhysiCell are often complex, require custom C++ code, are stored in project-specific repositories, are difficult to recompile and reproduce, and are poorly documented with respect to the precise PhysiBoSS or PhysiCell version on which they depend. The database responds by standardizing how models are stored, bundling the exact version of the PhysiBoSS/PhysiCell source with each model, providing cross-platform binaries so models can be run without compiling, and exposing models through a Python API and through PhysiCell Studio [2508.05550].

Within the underlying stack, PhysiCell is the open-source, physics-based agent-based modeling engine for 2D/3D multicellular systems, while PhysiBoSS is the add-on that embeds MaBoSS-style stochastic Boolean networks within each agent and couples intracellular decisions to the cell state and environment. PhysiBoSS-Models sits one level above this stack: it functions as a catalog of complete PhysiBoSS-based projects, each containing the PhysiBoSS/PhysiCell code at a specific revision, configuration files, Boolean models, any additional C++ logic, metadata, and documentation.

The initial scope at publication was deliberately narrow. The database was started with two peer-reviewed model entries: the PhysiBoSS tutorial models and a cancer invasion model. This limited initial coverage was presented as a foundation for a growing repository as new models are published and curated.

## 2. Multiscale formalism and model representation

PhysiBoSS-Models stores models whose multiscale structure couples a spatial, physics-based agent-based model of cells and their microenvironment with stochastic, continuous-time Boolean models of intracellular signaling. At the intracellular level, PhysiBoSS incorporates MaBoSS, a continuous-time stochastic Boolean framework, to model the dynamics of gene regulatory and signaling pathways within each cell. In the logical formulation, each node $x_i \in \{0,1\}$ has an associated Boolean update function $f_i$, giving in a deterministic setting
\[
x_i(t+1) = f_i(x_1(t),\dots,x_n(t)).
\]
MaBoSS turns this into a continuous-time stochastic Boolean process by assigning transition rates to each node and performing asynchronous updates with Gillespie-like sampling. PhysiBoSS then runs one such stochastic Boolean system per cell agent; each cell contains an independent MaBoSS Boolean network instance that is updated asynchronously during the simulation [2406.18371].

The agent-based layer is provided by PhysiCell. Each cell is an agent with position, mechanics, motility, cell-cycle and death machinery, and interactions with diffusing substrates. PhysiCell also solves reaction–diffusion equations for microenvironmental quantities. In PhysiBoSS models, inputs to the Boolean network can be set from microenvironment conditions, cell–cell contacts, or cell attributes, while Boolean outputs can control agent-level behaviors such as cell-cycle entry, apoptosis, necrosis, motility, secretion, or cell-type conversion.

Repository-level model representation follows a standardized folder structure. Each model repository contains source code, including the core PhysiBoSS and PhysiCell C++ code pinned to specific commits or versions, any custom C++ modules implementing specialized behaviors, XML settings used by PhysiCell/PhysiBoSS, initial cell positions, cell rules, intracellular Boolean models in MaBoSS `.bnd` and `.cfg` format, and metadata files such as `README.md` and `model.yml`. The `model.yml` file provides machine-readable metadata, including model version, authors, associated publications, and the list of configuration files.

## 3. Repository architecture, versioning, and access mechanisms

PhysiBoSS-Models is organized on GitHub under the `PhysiBoSS-Models` organization. Each model is a repository with standardized layout, pinned PhysiBoSS/PhysiCell code, and tagged releases. Continuous integration pipelines compile submitted models and generate precompiled packages for Windows, macOS, and Linux, which is central to the project’s reproducibility goals [2508.05550].

Semantic versioning is integral to the database. Git tags define releases such as `1.0.0` and `2.0.0`, and the metadata file includes a `version` field. This enables users to retrieve exactly the version used in a published study and to cite a precise model release. The cancer invasion model was highlighted as an explicit example: the original model corresponds to version `1.0.0`, and a revised tutorial version corresponds to `2.0.0`.

Programmatic access is provided by a Python-based API. The API supports keyword-based search, downloading and unpacking models directly into user-defined directories, and metadata access for automated workflows. The paper does not enumerate exact function signatures as a formal specification, but it describes search, download, and metadata retrieval as the key operations. This makes PhysiBoSS-Models suitable not only for interactive use but also for incorporation into larger modeling pipelines.

PhysiCell Studio integration exposes the same repository contents through a graphical workflow. A user can launch PhysiCell Studio, select a model from the PhysiBoSS-Models list, select a configuration file for a particular scenario, and run and visualize the simulation without writing code. This GUI pathway is especially important because it separates model use from low-level compilation or C++ development.

## 4. Database contents and canonical model entries

At publication, the database focused on PhysiBoSS models, which are multiscale models combining a spatial agent-based population with an intracellular stochastic Boolean signaling or gene regulatory network. The first entries were the PhysiBoSS tutorial models and a cancer invasion model [2508.05550].

| Entry | Contents | Versioning note |
|---|---|---|
| PhysiBoSS tutorial models | TNF-mediated tumor death; mechanistic cell cycle controlled by a Boolean model; T-cell differentiation | Shared binary with multiple configuration files |
| Cancer invasion model | Multiscale model of different modes of cancer cell invasion | Versions `1.0.0` and `2.0.0` both available |

The tutorial package, described in more detail in the PhysiBoSS tutorial paper, demonstrates three distinct coupling patterns between PhysiCell and MaBoSS [2406.18371]. The TNF-mediated tumor death model studies how TNF treatment regimens lead to different tumor-cell fates such as survival, apoptosis, or non-apoptotic cell death. The mechanistic cell-cycle model uses a Boolean regulatory network to control cell-cycle transitions. The T-cell differentiation model studies differentiation driven by cell–cell interactions, with extracellular signals and contact events setting logical nodes that determine lineage commitment.

The cancer invasion model addresses how physical parameters such as adhesion and motility, together with intracellular signaling pathways, control different modes of invasion such as single-cell versus collective migration. In repository terms, it also serves as a demonstration of long-term maintenance: multiple published versions coexist, allowing replication of older and newer results under distinct tagged releases.

These entries illustrate that PhysiBoSS-Models is not merely a collection of Boolean networks. It is a repository of complete multiscale projects in which Boolean signaling, agent mechanics, microenvironmental fields, configuration, metadata, and executable artifacts are all versioned together.

## 5. Simulation workflow, curation, and reproducibility practices

A typical workflow begins by selecting a model through the GitHub organization, the Python API, or PhysiCell Studio. The model is then downloaded, after which one inspects the relevant XML configuration file corresponding to a particular scenario. That configuration determines the microenvironment definition, cell types and their parameters, Boolean-network mappings, simulation time steps, total time, and output frequency. Execution can then proceed either from the command line using the included precompiled binary or from within PhysiCell Studio [2508.05550].

The database emphasizes reproducibility through exact code-version preservation, version-tagged releases, precompiled binaries, standardized metadata, and repository structure. Model repositories separate code, configuration, and metadata, and they encode the relationship between publication and implementation through explicit version fields and release tags. This ensures that reuse is not limited to conceptual reuse of a biological mechanism but extends to exact computational reproducibility.

Curation is editor-mediated. The submission procedure is described on the project website, and editors verify that submitted models are compatible with PhysiBoSS before they are added to the list. Validation procedures described in the database paper focus primarily on structural correctness, compatibility with the PhysiBoSS integration, and continuous-integration compilation and packaging tests. Scientific validation against experiments remains the responsibility of the underlying model publications rather than the repository paper itself.

The same reproducibility logic extends to model modification and extension. The papers describe a workflow in which one edits or replaces the MaBoSS `.bnd` and `.cfg` files, updates the XML mapping if new nodes or outputs are introduced, modifies cell definitions or the microenvironment in XML, and then reuses the repository’s versioning and documentation conventions. This suggests that PhysiBoSS-Models functions both as an archive and as a template for reproducible multiscale model development.

## 6. PhysiBench as a large standardized extension of the PhysiBoSS-Models concept

PhysiBench was explicitly designed as a large, standardized extension of the PhysiBoSS-Models concept. It takes the idea of sharing multiscale PhysiBoSS/PhysiCell models and turns it into a controlled benchmark suite plus a massive precomputed simulation dataset. PhysiBench contains a benchmark suite of 612 executable intracellular Boolean regulatory network variants and a dataset of 120,000 time-resolved multiscale stochastic simulations [2606.18215].

At the core of PhysiBench, every model is a MaBoSS/PhysiBoSS Boolean regulatory network embedded in PhysiCell agents. Each cell carries an independent stochastic Boolean network instance, updated asynchronously during the simulation. The PhysiCell environment provides a spatial domain, diffusion fields, cell mechanics, and cell-cycle/death machinery; PhysiBoSS couples these to the Boolean layer. In PhysiBench, that coupling is standardized through a common interface consisting of one Boolean input node and three Boolean output nodes for all models. The input node receives a scalar stimulation signal from the microenvironment, encoded through boundary conditions in the TNF-like field, and the three output nodes are read at each Boolean update and mapped to cell-level behaviors such as survival, proliferation, and death.

The seven base PhysiBoSS-compatible source models from which these variants are derived span mammalian cell-cycle restriction-point control, Drosophila segment polarity, EGF/TNF signaling, gastric cancer signaling, macrophage activation, prostate cancer signaling, and TNF cell fate. These source models are first converted to a common PhysiBoSS-compatible interface and MaBoSS format. One input plus three output nodes are defined and reserved, and these nodes are protected during subsequent variant generation so that every variant remains plug-compatible with the same PhysiBoSS/PhysiCell coupling.

Variant generation proceeds by mutation-based model construction, online behavioral filtering, and offline sensitivity evaluation. Mutation operators include `switch_nodes_logic`, `replace_logical_operator`, `replace_node_inside_logic`, `negate_subexpression`, `add_input_to_logic`, `add_new_node`, and `randomize_node_logic`. A disabled operator, `randomize_parameter`, exists but is not used in this release. The process is constrained so that at most 45 new nodes can be added in one lineage and the overall maximum network size after interface standardization is 63 nodes. Online filtering uses 48 stimulation protocols and final alive-cell counts at six saved time points to build a behavioral signature vector of dimension 288 for each model; a candidate is retained only if its maximum Pearson correlation with accepted models is below 0.85. Offline filtering then evaluates responsiveness across 215 released simulation contexts using nine summary outputs, retaining only models for which, for every output, $\sigma_{m,y} > 30.0$ and $\mathrm{CV}_{m,y} > 0.2$.

From the 612 executable models, 60 are selected for large-scale simulation: 30 high-variability models and 30 outlier-response models, with redundancy controlled by pairwise correlation. For each selected model, 2,000 simulation contexts are sampled from a systematic stimulation-protocol space defined by `treatment_duration`, `treatment_period`, and four TNF Dirichlet boundary values, yielding 120,000 time-resolved stochastic simulations. Each simulation is linked to its model identifier, input-parameter file, stochastic seed, and cell-level output file. Stored artifacts include `multiscale_simulations_manifest.json`, per-simulation `input_parameters_<simulation_ID>.json`, compressed `cell_data_<simulation_ID>.json.gz`, and the fixed per-model configuration files such as `initial_positions.json` and the Boolean `.bnd` and `.cfg` files.

PhysiBench supports direct simulation, surrogate modeling, data-driven inference, simulation-based optimization, and comparative benchmarking. Technical validation includes file-integrity and executability checks, graph-based structural diversity analyses using DeltaCon, Ipsen–Mikhailov, and Quantum Jensen–Shannon distances, and behavioral heterogeneity assessment from multiscale simulation outputs. A plausible implication is that PhysiBench transforms the repository logic of PhysiBoSS-Models into a benchmark ecosystem in which executability, interoperability, and reproducibility are controlled at scale rather than only repository by repository.

## 7. Limitations, caveats, and future directions

Several limitations were stated directly for PhysiBoSS-Models at publication. Coverage was still limited, initially to a small number of models. The resource was tool-specific, centered on models built with PhysiBoSS. Browsing was mainly through GitHub and the Python API rather than a rich web portal. Standardized reference simulation outputs were not yet provided, so users still needed to execute models themselves [2508.05550].

The roadmap in the database paper included expansion beyond PhysiBoSS to any model built with PhysiCell, extension of continuous-integration workflows to run standard simulations and store output data alongside models, development of a higher-quality web interface for browsing metadata and simulation outcomes, and broader community expansion. These plans indicate that the repository was conceived as an extensible infrastructure rather than as a fixed static archive.

The PhysiBench paper makes explicit a different class of caveat for large-scale benchmark use: the models are synthetic in silico benchmarks, not calibrated biological models; they use a Boolean formalism with switch-like dynamics; simulations are 2D; and the stimulation protocol is an abstract input signal rather than a detailed pharmacokinetic/pharmacodynamic model [2606.18215]. This suggests a clear boundary between methodological benchmarking and direct biological interpretation. For methodological work on PhysiBoSS surrogate modeling, optimization of treatment protocols in silico, or multiscale sensitivity analysis, this abstraction is deliberate; for mechanistic or translational interpretation, the abstraction imposes obvious constraints.

Taken together, PhysiBoSS-Models and its benchmark-oriented extension define a reproducibility-centered ecosystem for multiscale modeling in which intracellular Boolean logic, agent-based cell populations, software versioning, executability, and standardized access are treated as jointly essential components rather than separate concerns.

Source: https://www.emergentmind.com/topics/physiboss-models