API Reference¶

Auto-generated from source docstrings. For narrative usage examples see Advanced Features.

PhysiCellConfig¶

PhysiCellConfig ¶

Main PhysiCell configuration class using modular composition.

This class provides a single interface for building PhysiCell XML configurations while delegating functionality to specialized modules for maintainability.

init ¶

__init__()

Initialize the configuration with all modules.

set_xml_order ¶

set_xml_order(order: List[str]) -> None

Set the order of top-level XML elements.

from_xml `classmethod` ¶

from_xml(filename: Union[str, Path]) -> PhysiCellConfig

Create PhysiCellConfig instance from XML file.

Args: filename: Path to PhysiCell XML configuration file

Returns: New PhysiCellConfig instance with loaded configuration

Example: config = PhysiCellConfig.from_xml("PhysiCell_settings.xml")

from_xml_string `classmethod` ¶

from_xml_string(xml_content: str) -> PhysiCellConfig

Create PhysiCellConfig instance from XML string.

Args: xml_content: XML configuration as string

Returns: New PhysiCellConfig instance with loaded configuration

load_xml ¶

load_xml(filename: Union[str, Path], merge: bool = False) -> None

Load XML configuration into existing instance.

Args: filename: Path to XML file merge: If True, merge with existing config. If False, replace.

validate_xml_file ¶

validate_xml_file(filename: Union[str, Path]) -> Tuple[bool, str]

Validate that an XML file is a valid PhysiCell configuration.

Args: filename: Path to XML file to validate

Returns: Tuple of (is_valid, error_message)

load_xml_string ¶

load_xml_string(xml_content: str, merge: bool = False) -> None

Load XML from string into existing instance.

Args: xml_content: XML configuration as string merge: If True, merge with existing config. If False, replace.

copy ¶

copy() -> PhysiCellConfig

Create deep copy of configuration.

Returns: New PhysiCellConfig instance with identical configuration

add_user_parameter ¶

add_user_parameter(name: str, value: Any, units: str = 'dimensionless', description: str = '', parameter_type: str = 'double') -> None

Add a user parameter.

set_number_of_cells ¶

set_number_of_cells(count: int) -> None

Set the number of cells for initial placement.

Args: count: Number of cells to place initially for each cell type. Set to 0 if using custom cell.csv file for initial conditions.

setup_basic_simulation ¶

setup_basic_simulation(x_range: Tuple[float, float] = (-500, 500), y_range: Tuple[float, float] = (-500, 500), mesh_spacing: float = 20.0, max_time: float = 8640.0) -> None

Setup a basic simulation with common parameters.

add_simple_substrate ¶

add_simple_substrate(name: str, diffusion_coeff: float = 1000.0, decay_rate: float = 0.1, initial_value: float = 0.0) -> None

Add a simple substrate with common parameters.

add_simple_cell_type ¶

add_simple_cell_type(name: str, secretion_substrate: str = None, secretion_rate: float = 0.0, motile: bool = False) -> None

Add a simple cell type with common parameters.

generate_xml ¶

generate_xml() -> str

Generate the complete XML configuration.

save_xml ¶

save_xml(filename: str) -> None

Save the XML configuration to a file.

get_summary ¶

get_summary() -> Dict[str, Any]

Get a summary of the current configuration.

validate ¶

validate() -> List[str]

Validate the configuration and return list of issues.

set_parallel_settings ¶

set_parallel_settings(omp_num_threads: int = 4) -> None

Set parallel processing settings.

Modules¶

CellTypeModule¶

CellTypeModule ¶

Bases: BaseModule

Manage multiple cell types and their phenotypes.

add_cell_type ¶

add_cell_type(name: str, parent_type: str = 'default', template: str = 'default') -> None

Create a new cell type entry.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique identifier for the cell type.	required
`parent_type`	`str`	Name of the parent type to inherit from, usually `"default"`.	`'default'`
`template`	`str`	Template key from `cell_type_templates` defined in embedded default parameters. Each entry bundles the cycle model, phenotype defaults and optional intracellular settings used to populate the new cell type.	`'default'`

set_cycle_model ¶

set_cycle_model(cell_type: str, model: str) -> None

Assign a predefined cell cycle model to cell_type.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type to modify.	required
`model`	`str`	One of the models available via :func:`ConfigLoader.get_cycle_model`.	required

set_cycle_transition_rate ¶

set_cycle_transition_rate(cell_type: str, from_phase: int, to_phase: int, rate: float) -> None

Set a specific transition rate between cycle phases.

set_cycle_phase_durations ¶

set_cycle_phase_durations(cell_type: str, durations: list) -> None

Set cycle phase durations for a cell type.

This clears any transition rates so the XML output uses <phase_durations> instead of <phase_transition_rates>. Both formats are valid in PhysiCell.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type to modify.	required
`durations`	`list`	List of dicts, each with keys `index` (int), `duration` (float), and `fixed_duration` (bool).	required

Example

config.cell_types.set_cycle_phase_durations('default', [ ... {'index': 0, 'duration': 300.0, 'fixed_duration': False}, ... {'index': 1, 'duration': 480.0, 'fixed_duration': True}, ... {'index': 2, 'duration': 240.0, 'fixed_duration': True}, ... {'index': 3, 'duration': 60.0, 'fixed_duration': True}, ... ])

set_death_rate ¶

set_death_rate(cell_type: str, death_type: str, rate: float) -> None

Set death rate for a cell type.

set_death_parameters ¶

set_death_parameters(cell_type: str, death_type: str, **params) -> None

Set death model sub-parameters for a cell type.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required
`death_type`	`str`	`'apoptosis'` or `'necrosis'`.	required
`**params`		Keyword arguments corresponding to death model parameter names. Valid keys: `unlysed_fluid_change_rate`, `lysed_fluid_change_rate`, `cytoplasmic_biomass_change_rate`, `nuclear_biomass_change_rate`, `calcification_rate`, `relative_rupture_volume`.	`{}`

Example

config.cell_types.set_death_parameters('default', 'necrosis', ... unlysed_fluid_change_rate=0.05, ... cytoplasmic_biomass_change_rate=0.0166667, ... )

set_death_phase_durations ¶

set_death_phase_durations(cell_type: str, death_type: str, durations: list) -> None

Set death model phase durations (removes any phase_transition_rates).

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required
`death_type`	`str`	`'apoptosis'` or `'necrosis'`.	required
`durations`	`list`	List of dicts with `index`, `duration`, `fixed_duration`.	required

Example

config.cell_types.set_death_phase_durations('Treg', 'apoptosis', [ ... {'index': 0, 'duration': 0.0, 'fixed_duration': True}, ... ])

set_death_phase_transition_rates ¶

set_death_phase_transition_rates(cell_type: str, death_type: str, rates: list) -> None

Set death model phase transition rates (removes any phase_durations).

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required
`death_type`	`str`	`'apoptosis'` or `'necrosis'`.	required
`rates`	`list`	List of dicts with `start_index`, `end_index`, `rate`, `fixed_duration`.	required

Example

config.cell_types.set_death_phase_transition_rates( ... 'M0 macrophage', 'necrosis', [ ... {'start_index': 0, 'end_index': 1, 'rate': 9e9, 'fixed_duration': False}, ... {'start_index': 1, 'end_index': 2, 'rate': 1.15741e-05, 'fixed_duration': True}, ... ])

set_cell_adhesion_affinities ¶

set_cell_adhesion_affinities(cell_type: str, affinities: dict) -> None

Set per-cell-type adhesion affinities.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type to modify.	required
`affinities`	`dict`	Dictionary mapping target cell type names to affinity values. Replaces any existing affinities (including the placeholder `"default"` key).	required

Example

config.cell_types.set_cell_adhesion_affinities('M0 macrophage', { ... 'malignant epithelial cell': 1.0, ... 'M0 macrophage': 1.0, ... 'effector T cell': 0.5, ... })

update_all_cell_types_for_adhesion_affinities ¶

update_all_cell_types_for_adhesion_affinities(default_affinity: float = 1.0) -> None

Populate adhesion affinities so every cell type has an entry for every other.

Existing non-default entries are preserved. The placeholder "default" key is removed and replaced with explicit per-cell-type entries.

Parameters:

Name	Type	Description	Default
`default_affinity`	`float`	Default affinity value for missing entries.	`1.0`

set_phagocytosis_rates ¶

set_phagocytosis_rates(cell_type: str, apoptotic: float = None, necrotic: float = None, other_dead: float = None) -> None

Set dead-cell phagocytosis rates.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required
`apoptotic`	`float`	Rate for phagocytosing apoptotic cells.	`None`
`necrotic`	`float`	Rate for phagocytosing necrotic cells.	`None`
`other_dead`	`float`	Rate for phagocytosing other dead cells.	`None`

Example

config.cell_types.set_phagocytosis_rates('M0 macrophage', ... apoptotic=0.01, necrotic=0.01, other_dead=0.01)

set_attack_rate ¶

set_attack_rate(cell_type: str, target_cell_type: str, rate: float) -> None

Set the attack rate for one cell type attacking another.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	The attacking cell type.	required
`target_cell_type`	`str`	The cell type being attacked.	required
`rate`	`float`	Attack rate in 1/min.	required

Example

config.cell_types.set_attack_rate('effector T cell', ... 'malignant epithelial cell', 0.01)

set_attack_parameters ¶

set_attack_parameters(cell_type: str, damage_rate: float = None, duration: float = None) -> None

Set attack damage rate and duration.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required
`damage_rate`	`float`	Attack damage rate in 1/min.	`None`
`duration`	`float`	Attack duration in min.	`None`

Example

config.cell_types.set_attack_parameters('effector T cell', ... damage_rate=1.0, duration=0.1)

set_transformation_rate ¶

set_transformation_rate(cell_type: str, target_cell_type: str, rate: float) -> None

Set the transformation rate from one cell type to another.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	The cell type that transforms.	required
`target_cell_type`	`str`	The cell type it transforms into.	required
`rate`	`float`	Transformation rate in 1/min.	required

Example

config.cell_types.set_transformation_rate('M1 macrophage', ... 'M2 macrophage', 0.001)

set_mechanics_parameters ¶

set_mechanics_parameters(cell_type: str, **params) -> None

Set mechanics parameters for a cell type.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required
`**params`		Keyword arguments. Valid keys: `cell_cell_adhesion_strength`, `cell_cell_repulsion_strength`, `relative_maximum_adhesion_distance`, `attachment_elastic_constant`, `attachment_rate`, `detachment_rate`, `maximum_number_of_attachments`.	`{}`

Example

config.cell_types.set_mechanics_parameters('M0 macrophage', ... cell_cell_adhesion_strength=0.0, ... relative_maximum_adhesion_distance=1.5, ... )

set_custom_data ¶

set_custom_data(cell_type: str, key: str, value, units: str = 'dimensionless', description: str = '', conserved: bool = False) -> None

Add or update a custom data entry for a cell type.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required
`key`	`str`	Name of the custom data variable.	required
`value`		Value of the variable (numeric or string).	required
`units`	`str`	Unit string (default `'dimensionless'`).	`'dimensionless'`
`description`	`str`	Optional description.	`''`
`conserved`	`bool`	Whether the quantity is conserved.	`False`

Example

config.cell_types.set_custom_data('M0 macrophage', 'sample', ... value=0.0, units='dimensionless')

clear_custom_data ¶

clear_custom_data(cell_type: str) -> None

Remove all custom data entries for a cell type.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required

set_volume_parameters ¶

set_volume_parameters(cell_type: str, total: float = None, nuclear: float = None, fluid_fraction: float = None) -> None

Set volume parameters for a cell type.

set_motility ¶

set_motility(cell_type: str, speed: float = None, persistence_time: float = None, migration_bias: float = None, enabled: bool = None) -> None

Set motility parameters for a cell type.

set_chemotaxis ¶

set_chemotaxis(cell_type: str, substrate: str, enabled: bool = True, direction: int = 1) -> None

Set chemotaxis parameters for a cell type.

Args: cell_type: Name of the cell type substrate: Name of the substrate to follow (must be a real substrate name) enabled: Whether chemotaxis is enabled direction: Direction of chemotaxis (1 for attraction, -1 for repulsion)

set_advanced_chemotaxis ¶

set_advanced_chemotaxis(cell_type: str, substrate_sensitivities: dict, enabled: bool = True, normalize_each_gradient: bool = False) -> None

Set advanced chemotaxis parameters for a cell type.

Args: cell_type: Name of the cell type substrate_sensitivities: Dictionary mapping substrate names to sensitivity values enabled: Whether advanced chemotaxis is enabled normalize_each_gradient: Whether to normalize each gradient

add_secretion ¶

add_secretion(cell_type: str, substrate: str, secretion_rate: float, secretion_target: float = 1.0, uptake_rate: float = 0.0, net_export_rate: float = 0.0) -> None

Add secretion parameters for a substrate.

update_all_cell_types_for_substrates ¶

update_all_cell_types_for_substrates() -> None

Update all cell types to include secretion parameters for all substrates.

update_all_cell_types_for_interactions ¶

update_all_cell_types_for_interactions() -> None

Populate interaction and transformation rates for all defined cell types.

For each cell type, ensures that live_phagocytosis_rates, attack_rates, fusion_rates, and transformation_rates contain an entry for every defined cell type (using 0.0 as the default rate). Existing non-default entries are preserved.

add_to_xml ¶

add_to_xml(parent: Element) -> None

Add cell types configuration to XML.

load_from_xml ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load cell type definitions from XML element.

Args: xml_element: XML element containing cell definitions, or None if missing

get_cell_types ¶

get_cell_types() -> Dict[str, Dict[str, Any]]

Get all cell types.

cell_type_exists ¶

cell_type_exists(cell_type: str) -> bool

Check if a cell type exists.

SubstrateModule¶

SubstrateModule ¶

Bases: BaseModule

Add substrates, boundary conditions and related options.

set_track_internalized_substrates ¶

set_track_internalized_substrates(enabled: bool) -> None

Set whether to track internalized substrates in each agent.

set_calculate_gradients ¶

set_calculate_gradients(enabled: bool) -> None

Enable/disable gradient computation in the microenvironment.

add_substrate ¶

add_substrate(name: str, diffusion_coefficient: float = 1000.0, decay_rate: float = 0.1, initial_condition: float = 0.0, dirichlet_enabled: bool = False, dirichlet_value: float = 0.0, units: str = 'dimensionless', initial_units: str = 'mmHg') -> None

Create a new diffusive substrate entry.

Parameters:

Name	Type	Description	Default
`name`	`str`	Substrate identifier.	required
`diffusion_coefficient`	`float`	Diffusion constant in micron^2/min.	`1000.0`
`decay_rate`	`float`	First-order decay rate `1/min`.	`0.1`
`initial_condition`	`float`	Initial concentration value.	`0.0`
`dirichlet_enabled`	`bool`	Global Dirichlet condition settings.	`False`
`dirichlet_value`	`bool`	Global Dirichlet condition settings.	`False`
`units`	`str`	Units for the concentration fields.	`'dimensionless'`
`initial_units`	`str`	Units for the concentration fields.	`'dimensionless'`

set_dirichlet_boundary ¶

set_dirichlet_boundary(substrate_name: str, boundary: str, enabled: bool, value: float = 0.0) -> None

Configure boundary-specific Dirichlet settings.

remove_substrate ¶

remove_substrate(name: str) -> None

Remove a substrate from the configuration.

add_to_xml ¶

add_to_xml(parent: Element) -> None

Add substrates configuration to XML.

load_from_xml ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load substrate configuration from XML element.

Args: xml_element: XML element containing microenvironment configuration, or None if missing

get_substrates ¶

get_substrates() -> Dict[str, Dict[str, Any]]

Get all substrates.

DomainModule¶

DomainModule ¶

Bases: BaseModule

Manage simulation bounds and mesh spacing.

set_bounds ¶

set_bounds(x_min: float, x_max: float, y_min: float, y_max: float, z_min: float = -10.0, z_max: float = 10.0) -> None

Configure the physical extents of the simulation space.

Parameters:

Name	Type	Description	Default
`x_min`	`float`	Coordinates describing the box boundaries in microns.	required
`x_max`	`float`	Coordinates describing the box boundaries in microns.	required
`y_min`	`float`	Coordinates describing the box boundaries in microns.	required
`y_max`	`float`	Coordinates describing the box boundaries in microns.	required
`z_min`	`float`	Coordinates describing the box boundaries in microns.	required
`z_max`	`float`	Coordinates describing the box boundaries in microns.	required

set_mesh ¶

set_mesh(dx: float, dy: float, dz: float = 20.0) -> None

Set the Cartesian mesh spacing in each dimension.

Parameters:

Name	Type	Description	Default
`dx`	`float`	Grid spacing in microns.	required
`dy`	`float`	Grid spacing in microns.	required
`dz`	`float`	Grid spacing in microns.	required

set_2D ¶

set_2D(use_2D: bool = True) -> None

Toggle 2‑D simulation mode.

Parameters:

Name	Type	Description	Default
`use_2D`	`bool`	`True` for planar simulations, `False` for 3‑D.	`True`

add_to_xml ¶

add_to_xml(parent: Element) -> None

Append domain settings to the output XML tree.

Parameters:

Name	Type	Description	Default
`parent`	`Element`	The root `PhysiCell_settings` XML element.	required

load_from_xml ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load domain configuration from XML element.

Args: xml_element: XML element containing domain configuration, or None if missing

get_info ¶

get_info() -> Dict[str, Any]

Return a copy of the current domain configuration.

OptionsModule¶

OptionsModule ¶

Bases: BaseModule

Configure general simulation options such as time steps.

set_max_time ¶

set_max_time(max_time: float, units: str = 'min') -> None

Define the total simulation duration.

Parameters:

Name	Type	Description	Default
`max_time`	`float`	Final time value.	required
`units`	`str`	Time units (`'min'` or `'hour'`).	`'min'`

set_time_steps ¶

set_time_steps(dt_diffusion: float = None, dt_mechanics: float = None, dt_phenotype: float = None) -> None

Specify numerical integration time steps.

Parameters:

Name	Type	Description	Default
`dt_diffusion`	`float`	Optional overrides for the default time steps.	`None`
`dt_mechanics`	`float`	Optional overrides for the default time steps.	`None`
`dt_phenotype`	`float`	Optional overrides for the default time steps.	`None`

set_virtual_wall ¶

set_virtual_wall(enabled: bool) -> None

Enable or disable the domain boundary wall.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	`True` to prevent cells leaving the domain.	required

set_automated_spring_adhesions ¶

set_automated_spring_adhesions(disabled: bool) -> None

Toggle automated spring adhesion feature.

set_random_seed ¶

set_random_seed(seed: int) -> None

Specify the random number generator seed.

set_legacy_random_points ¶

set_legacy_random_points(enabled: bool) -> None

Use legacy division positioning algorithm.

set_parallel_threads ¶

set_parallel_threads(num_threads: int) -> None

Set number of OpenMP threads used by the simulation.

add_to_xml ¶

add_to_xml(parent: Element) -> None

Add options configuration to XML.

load_from_xml ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load options configuration from XML element.

Args: xml_element: XML element containing overall options configuration, or None if missing

load_parallel_from_xml ¶

load_parallel_from_xml(xml_element: Optional[Element]) -> None

Load parallel configuration from XML element.

Args: xml_element: XML element containing parallel configuration, or None if missing

load_options_from_xml ¶

load_options_from_xml(xml_element: Optional[Element]) -> None

Load additional options configuration from XML element.

Args: xml_element: XML element containing additional options configuration, or None if missing

get_options ¶

get_options() -> Dict[str, Any]

Get all options.

SaveOptionsModule¶

SaveOptionsModule ¶

Bases: BaseModule

Configure data output intervals and formats.

set_output_folder ¶

set_output_folder(folder: str) -> None

Set output folder.

set_full_data_options ¶

set_full_data_options(interval: float = None, enable: bool = None, settings_interval: float = None) -> None

Set full data save options.

set_svg_options ¶

set_svg_options(interval: float = None, enable: bool = None) -> None

Set SVG save options.

set_svg_plot_substrate ¶

set_svg_plot_substrate(enabled: bool = False, limits: bool = False, substrate: str = 'substrate', colormap: str = 'YlOrRd', min_conc: float = 0, max_conc: float = 1) -> None

Configure plotting of a substrate concentration in SVG outputs.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	Turn substrate plots on or off.	`False`
`limits`	`bool`	Whether min/max concentration limits are enforced.	`False`
`substrate`	`str`	Name of the substrate to visualise.	`'substrate'`
`colormap`	`str`	Matplotlib-style colormap name.	`'YlOrRd'`
`min_conc`	`float`	Colour scale bounds.	`0`
`max_conc`	`float`	Colour scale bounds.	`0`

set_svg_legend ¶

set_svg_legend(enabled: bool = False, cell_phase: bool = False, cell_type: bool = True) -> None

Control the presence and contents of the SVG legend.

set_legacy_data ¶

set_legacy_data(enable: bool) -> None

Output additional legacy-format data files.

add_to_xml ¶

add_to_xml(parent: Element) -> None

Add save options configuration to XML.

load_from_xml ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load save options configuration from XML element.

Args: xml_element: XML element containing save options configuration, or None if missing

get_save_options ¶

get_save_options() -> Dict[str, Any]

Get all save options.

InitialConditionsModule¶

InitialConditionsModule ¶

Bases: BaseModule

Define initial cell locations and placement files.

add_cell_cluster ¶

add_cell_cluster(cell_type: str, x: float, y: float, z: float = 0.0, radius: float = 100.0, num_cells: int = 100) -> None

Place a spherical cluster of cells.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Cell type name.	required
`x`	`float`	Coordinates of the cluster centre.	required
`y`	`float`	Coordinates of the cluster centre.	required
`z`	`float`	Coordinates of the cluster centre.	required
`radius`	`float`	Sphere radius in microns.	`100.0`
`num_cells`	`int`	Number of cells to generate.	`100`

add_single_cell ¶

add_single_cell(cell_type: str, x: float, y: float, z: float = 0.0) -> None

Place one cell in the simulation domain.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Cell type name.	required
`x`	`float`	Coordinates of the cell.	required
`y`	`float`	Coordinates of the cell.	required
`z`	`float`	Coordinates of the cell.	required

add_rectangular_region ¶

add_rectangular_region(cell_type: str, x_min: float, x_max: float, y_min: float, y_max: float, z_min: float = -5.0, z_max: float = 5.0, density: float = 0.8) -> None

Fill a rectangular region with randomly placed cells.

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type.	required
`x_min`	`float`	Bounds of the region.	required
`x_max`	`float`	Bounds of the region.	required
`y_min`	`float`	Bounds of the region.	required
`y_max`	`float`	Bounds of the region.	required
`z_min`	`float`	Bounds of the region.	required
`z_max`	`float`	Bounds of the region.	required
`density`	`float`	Fraction of the region volume filled with cells (0-1).	`0.8`

add_csv_file ¶

add_csv_file(filename: str, folder: str = './config', enabled: bool = False) -> None

Specify an external CSV file for cell positions.

Parameters:

Name	Type	Description	Default
`filename`	`str`	CSV file name.	required
`folder`	`str`	Folder containing the file.	`'./config'`
`enabled`	`bool`	Whether PhysiCell should load the file.	`False`

add_to_xml ¶

add_to_xml(parent: Element) -> None

Add initial conditions configuration to XML.

load_from_xml ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load initial conditions configuration from XML element.

Args: xml_element: XML element containing initial conditions configuration, or None if missing

get_conditions ¶

get_conditions() -> List[Dict[str, Any]]

Return a copy of all currently defined explicit placements.

clear_conditions ¶

clear_conditions() -> None

Remove all stored initial conditions.

CellRulesModule¶

CellRulesModule ¶

Bases: BaseModule

Handles cell rules configuration for PhysiCell simulations.

This module manages both sides of PhysiCell's cell-rules system:

XML side – the <cell_rules><rulesets> section that tells PhysiCell which CSV files to load at runtime (:meth:add_ruleset, :meth:add_to_xml).
CSV content side – the actual rules written into those CSV files (:meth:add_rule, :meth:save_rules_to_csv / :meth:generate_csv).

An embedded registry of known signals and behaviors is loaded on construction and used for soft validation (warnings, not hard errors). Call :meth:update_context_from_config (or access through PhysiCellConfig) to keep the registry context in sync with the cell types and substrates defined in your configuration.

update_context_from_config ¶

update_context_from_config(config: PhysiCellConfig) -> None

Sync available cell types and substrates from config.

Call this whenever you add new cell types or substrates so that the validation warnings stay accurate.

Parameters:

Name	Type	Description	Default
`config`	`PhysiCellConfig`	The :class:`~physicell_config.config_builder_modular.PhysiCellConfig` instance to read cell types and substrates from.	required

get_available_signals ¶

get_available_signals(filter_by_type: Optional[str] = None) -> Dict[str, Dict[str, Any]]

Return available signals, optionally filtered by type.

Parameters:

Name	Type	Description	Default
`filter_by_type`	`Optional[str]`	If given, only signals whose `type` field matches this string are returned (e.g. `'contact'`, `'substrate'`).	`None`

get_available_behaviors ¶

get_available_behaviors(filter_by_type: Optional[str] = None) -> Dict[str, Dict[str, Any]]

Return available behaviors, optionally filtered by type.

Parameters:

Name	Type	Description	Default
`filter_by_type`	`Optional[str]`	If given, only behaviors whose `type` field matches this string are returned (e.g. `'interaction'`, `'motility'`).	`None`

get_context ¶

get_context() -> Dict[str, List[str]]

Return current context (cell types, substrates, custom variables).

get_signal_by_name ¶

get_signal_by_name(signal_name: str) -> Optional[Dict[str, Any]]

Look up a signal by its human-readable name.

Returns:

Type	Description
`dict or None`	Signal metadata dict (including `'id'`) or `None` if not found.

get_behavior_by_name ¶

get_behavior_by_name(behavior_name: str) -> Optional[Dict[str, Any]]

Look up a behavior by its human-readable name.

Returns:

Type	Description
`dict or None`	Behavior metadata dict (including `'id'`) or `None` if not found.

add_ruleset ¶

add_ruleset(name: str, folder: str = './config', filename: str = 'rules.csv', enabled: bool = True) -> None

Register a CSV ruleset.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier for the ruleset.	required
`folder`	`str`	Folder where the CSV file resides.	`'./config'`
`filename`	`str`	Name of the CSV file containing the rules.	`'rules.csv'`
`enabled`	`bool`	Whether the ruleset should be loaded by PhysiCell.	`True`

add_rule ¶

add_rule(cell_type: str, signal: str, direction: str, behavior: str, saturation_value: float = 0.0, half_max: float = 0.5, hill_power: float = 4.0, apply_to_dead: int = 0) -> None

Add a single rule following the PhysiCell CBHG v3.0 CSV format.

Hard errors are raised for invalid direction or apply_to_dead values. Unrecognised signal/behavior names produce a warning (the registry may not cover every custom name you define).

Parameters:

Name	Type	Description	Default
`cell_type`	`str`	Name of the cell type this rule applies to.	required
`signal`	`str`	Signal that triggers the behavior (e.g. `'oxygen'`, `'contact with tumor'`).	required
`direction`	`str`	`'increases'` or `'decreases'` — how the signal affects the behavior.	required
`behavior`	`str`	The behavior being modulated (e.g. `'cycle entry'`, `'apoptosis'`, `'migration speed'`).	required
`saturation_value`	`float`	Value of the behavior when the signal is at saturation.	`0.0`
`half_max`	`float`	Signal value at which the behavior is halfway between its base value and the saturation value.	`0.5`
`hill_power`	`float`	Exponent of the Hill function controlling the response curve.	`4.0`
`apply_to_dead`	`int`	`1` if the rule should be evaluated for dead cells, `0` otherwise.	`0`

load_rules_from_csv ¶

load_rules_from_csv(filename: str) -> None

Read rule definitions from a PhysiCell rules CSV file.

The CSV is expected to have no header row and follow the CBHG v3.0 column order::

cell_type,signal,direction,behavior,saturation_value,half_max,hill_power,apply_to_dead

Parameters:

Name	Type	Description	Default
`filename`	`str`	Path to the CSV file.	required

save_rules_to_csv ¶

save_rules_to_csv(filename: str) -> None

Write all currently stored rules to a PhysiCell-compatible CSV file.

The output has no header row and follows the CBHG v3.0 column order::

cell_type,signal,direction,behavior,saturation_value,half_max,hill_power,apply_to_dead

Parameters:

Name	Type	Description	Default
`filename`	`str`	Destination path for the generated CSV.	required

generate_csv ¶

generate_csv(filename: str) -> str

Alias for :meth:save_rules_to_csv that returns the filename.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Destination path for the generated CSV.	required

Returns:

Type	Description
`str`	The filename that was written.

remove_rule ¶

remove_rule(index: int) -> None

Remove a rule by its list index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Zero-based index of the rule to remove.	required

Raises:

Type	Description
`IndexError`	If index is out of range.

validate_rules ¶

validate_rules() -> List[str]

Validate all stored rules against the registry.

Returns:

Type	Description
`list of str`	Validation warning/error messages. An empty list means all rules passed.

print_available_signals ¶

print_available_signals(filter_by_type: Optional[str] = None) -> None

Print available signals in a readable format.

Parameters:

Name	Type	Description	Default
`filter_by_type`	`Optional[str]`	Optional signal type to filter by (e.g. `'contact'`, `'substrate'`).	`None`

print_available_behaviors ¶

print_available_behaviors(filter_by_type: Optional[str] = None) -> None

Print available behaviors in a readable format.

Parameters:

Name	Type	Description	Default
`filter_by_type`	`Optional[str]`	Optional behavior type to filter by (e.g. `'interaction'`, `'motility'`).	`None`

print_context ¶

print_context() -> None

Print the current context (cell types, substrates, custom variables).

print_rules ¶

print_rules() -> None

Print all current rules in a readable table.

add_to_xml ¶

add_to_xml(parent: Element) -> None

Serialize cell rules into the PhysiCell XML tree.

Parameters:

Name	Type	Description	Default
`parent`	`Element`	Parent XML element representing `microenvironment_setup`.	required

load_from_xml ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load cell rules configuration from XML element.

Args: xml_element: XML element containing cell rules configuration, or None if missing

get_rules ¶

get_rules() -> List[Dict[str, Any]]

Return a copy of all stored rule dictionaries.

get_rulesets ¶

get_rulesets() -> Dict[str, Dict[str, Any]]

Return a copy of the registered rulesets.

clear_rules ¶

clear_rules() -> None

Remove every rule from the internal list.

clear_rulesets ¶

clear_rulesets() -> None

Remove all registered rulesets.

PhysiBoSSModule¶

PhysiBoSSModule ¶

Bases: BaseModule

Configure PhysiBoSS integration for per-cell-type intracellular models.

add_intracellular_model ¶

add_intracellular_model(cell_type_name: str, model_type: str = 'maboss', bnd_filename: str = '', cfg_filename: str = '') -> None

Add intracellular model to a cell type.

Parameters:

Name	Type	Description	Default
`cell_type_name`	`str`	Name of the cell type	required
`model_type`	`str`	Type of intracellular model (default: 'maboss')	`'maboss'`
`bnd_filename`	`str`	Boolean network file name	`''`
`cfg_filename`	`str`	Configuration file name	`''`

set_intracellular_settings ¶

set_intracellular_settings(cell_type_name: str, intracellular_dt: float = None, time_stochasticity: int = None, scaling: float = None, start_time: float = None, inheritance_global: bool = None) -> None

Set intracellular model settings for a cell type.

Parameters:

Name	Type	Description	Default
`cell_type_name`	`str`	Name of the cell type	required
`intracellular_dt`	`float`	Intracellular time step	`None`
`time_stochasticity`	`int`	Time stochasticity parameter	`None`
`scaling`	`float`	Scaling factor	`None`
`start_time`	`float`	Start time	`None`
`inheritance_global`	`bool`	Global inheritance setting	`None`

add_intracellular_initial_value ¶

add_intracellular_initial_value(cell_type_name: str, intracellular_name: str, value: float) -> None

Set initial value for an intracellular node.

Parameters:

Name	Type	Description	Default
`cell_type_name`	`str`	Name of the cell type	required
`intracellular_name`	`str`	Name of the intracellular node	required
`value`	`float`	Initial value	required

add_intracellular_input ¶

add_intracellular_input(cell_type_name: str, physicell_name: str, intracellular_name: str, action: str = 'activation', threshold: float = 1, smoothing: int = 0) -> None

Add an input mapping for the intracellular model.

Parameters:

Name	Type	Description	Default
`cell_type_name`	`str`	Name of the cell type	required
`physicell_name`	`str`	PhysiCell variable name	required
`intracellular_name`	`str`	Intracellular variable name	required
`action`	`str`	Action type (default: 'activation')	`'activation'`
`threshold`	`float`	Threshold value (default: 1)	`1`
`smoothing`	`int`	Smoothing parameter (default: 0)	`0`

add_intracellular_output ¶

add_intracellular_output(cell_type_name: str, physicell_name: str, intracellular_name: str, action: str = 'activation', value: float = 1000000, base_value: float = 0, smoothing: int = 0) -> None

Add an output mapping for the intracellular model.

Parameters:

Name	Type	Description	Default
`cell_type_name`	`str`	Name of the cell type	required
`physicell_name`	`str`	PhysiCell variable name	required
`intracellular_name`	`str`	Intracellular variable name	required
`action`	`str`	Action type (default: 'activation')	`'activation'`
`value`	`float`	Output value (default: 1000000)	`1000000`
`base_value`	`float`	Base value (default: 0)	`0`
`smoothing`	`int`	Smoothing parameter (default: 0)	`0`

add_intracellular_mutation ¶

add_intracellular_mutation(cell_type_name: str, intracellular_name: str, value: Union[str, bool]) -> None

Add an intracellular mutation for a cell type.

Parameters:

Name	Type	Description	Default
`cell_type_name`	`str`	Name of the cell type	required
`intracellular_name`	`str`	Name of the intracellular variable	required
`value`	`Union[str, bool]`	Value for the mutation	required

add_intracellular_xml ¶

add_intracellular_xml(parent_elem, cell_type_name: str) -> None

Add intracellular model XML elements for a specific cell type.

Parameters:

Name	Type	Description	Default
`parent_elem`	`Element`	Parent XML element (typically phenotype)	required
`cell_type_name`	`str`	Name of the cell type	required

load_from_xml ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load PhysiBoSS configuration from a cell_definitions XML element.

Detailed per-cell intracellular data is parsed by CellTypeModule.load_from_xml(); this method only updates the top-level enabled flag so that :meth:is_enabled stays consistent when the module is interrogated before cell-type loading completes.

Args: xml_element: cell_definitions XML element, or None if the section is absent.

is_enabled ¶

is_enabled() -> bool

Check if PhysiBoSS is enabled.

Returns True if any cell type has intracellular models configured.

ConfigLoader¶

ConfigLoader ¶

Loader for default PhysiCell configuration snippets.

The loader uses embedded Python data structures instead of JSON files to provide convenience methods for retrieving common phenotype or substrate templates.

config `property` ¶

config: Dict[str, Any]

Lazy load configuration from embedded data.

get_cycle_model ¶

get_cycle_model(model_name: str) -> Dict[str, Any]

Get cycle model configuration by name.

get_death_model ¶

get_death_model(model_name: str) -> Dict[str, Any]

Get death model configuration by name.

get_volume_defaults ¶

get_volume_defaults() -> Dict[str, Any]

Get default volume parameters.

get_mechanics_defaults ¶

get_mechanics_defaults() -> Dict[str, Any]

Get default mechanics parameters.

get_motility_defaults ¶

get_motility_defaults() -> Dict[str, Any]

Get default motility parameters.

get_secretion_defaults ¶

get_secretion_defaults() -> Dict[str, Any]

Get default secretion parameters.

get_cell_interactions_defaults ¶

get_cell_interactions_defaults() -> Dict[str, Any]

Get default cell interactions parameters.

get_cell_transformations_defaults ¶

get_cell_transformations_defaults() -> Dict[str, Any]

Get default cell transformations parameters.

get_cell_integrity_defaults ¶

get_cell_integrity_defaults() -> Dict[str, Any]

Get default cell integrity parameters.

get_custom_data_defaults ¶

get_custom_data_defaults(data_type: str = 'sample') -> Dict[str, Any]

Get default custom data parameters.

get_initial_parameter_distributions_defaults ¶

get_initial_parameter_distributions_defaults() -> Dict[str, Any]

Get default initial parameter distributions.

get_intracellular_defaults ¶

get_intracellular_defaults(intracellular_type: str = 'maboss') -> Dict[str, Any]

Get default intracellular parameters.

get_cell_type_template ¶

get_cell_type_template(template_name: str) -> Dict[str, Any]

Get cell type template configuration.

get_substrate_defaults ¶

get_substrate_defaults(substrate_name: str = 'substrate') -> Dict[str, Any]

Get default substrate parameters.

get_default_phenotype ¶

get_default_phenotype(template: str = 'default') -> Dict[str, Any]

Create a complete default phenotype based on template.

BaseModule¶

BaseModule ¶

Bases: ABC

Base class for all configuration modules.

Parameters:

Name	Type	Description	Default
`config`	`PhysiCellConfig`	Parent :class:`PhysiCellConfig` instance used for cross-module communication.	required

init ¶

__init__(config: PhysiCellConfig)

Store a reference to the parent configuration object.

load_from_xml `abstractmethod` ¶

load_from_xml(xml_element: Optional[Element]) -> None

Load module configuration from XML element.

Args: xml_element: XML element containing module data, or None if section missing

merge_from_xml ¶

merge_from_xml(xml_element: Optional[Element]) -> None

Merge XML configuration with existing module data.

Default implementation calls load_from_xml. Override for custom merge logic.

Args: xml_element: XML element containing module data, or None if section missing

API Reference¶

PhysiCellConfig¶

PhysiCellConfig ¶

__init__ ¶

set_xml_order ¶

from_xml classmethod ¶

from_xml_string classmethod ¶

load_xml ¶

validate_xml_file ¶

load_xml_string ¶

copy ¶

add_user_parameter ¶

set_number_of_cells ¶

setup_basic_simulation ¶

add_simple_substrate ¶

add_simple_cell_type ¶

generate_xml ¶

save_xml ¶

get_summary ¶

validate ¶

set_parallel_settings ¶

Modules¶

CellTypeModule¶

CellTypeModule ¶

add_cell_type ¶

set_cycle_model ¶

set_cycle_transition_rate ¶

set_cycle_phase_durations ¶

set_death_rate ¶

set_death_parameters ¶

set_death_phase_durations ¶

set_death_phase_transition_rates ¶

set_cell_adhesion_affinities ¶

update_all_cell_types_for_adhesion_affinities ¶

set_phagocytosis_rates ¶

set_attack_rate ¶

set_attack_parameters ¶

set_transformation_rate ¶

set_mechanics_parameters ¶

set_custom_data ¶

clear_custom_data ¶

set_volume_parameters ¶

set_motility ¶

set_chemotaxis ¶

set_advanced_chemotaxis ¶

add_secretion ¶

update_all_cell_types_for_substrates ¶

update_all_cell_types_for_interactions ¶

add_to_xml ¶

load_from_xml ¶

get_cell_types ¶

cell_type_exists ¶

SubstrateModule¶

SubstrateModule ¶

set_track_internalized_substrates ¶

set_calculate_gradients ¶

add_substrate ¶

set_dirichlet_boundary ¶

remove_substrate ¶

add_to_xml ¶

load_from_xml ¶

get_substrates ¶

DomainModule¶

DomainModule ¶

set_bounds ¶

set_mesh ¶

set_2D ¶

add_to_xml ¶

load_from_xml ¶

get_info ¶

OptionsModule¶

OptionsModule ¶

set_max_time ¶

set_time_steps ¶

set_virtual_wall ¶

set_automated_spring_adhesions ¶

set_random_seed ¶

set_legacy_random_points ¶

set_parallel_threads ¶

add_to_xml ¶

init ¶

from_xml `classmethod` ¶

from_xml_string `classmethod` ¶

config `property` ¶