Skip to content

PhysiCell Settings API Reference

This page summarizes the public API provided by the physicell_config package. Each section lists the available classes and methods along with a short explanation of their purpose and parameters.

PhysiCellConfig

Located in physicell_config/config_builder_modular.py. This class orchestrates all configuration modules and provides convenience helpers to generate and save complete PhysiCell XML files.

Methods

  • __init__() – instantiate the builder and all modules.
  • add_user_parameter(name, value, units='dimensionless', description='', parameter_type='double') – register a custom user parameter.
  • set_number_of_cells(count) – convenience setter for the standard number_of_cells parameter.
  • setup_basic_simulation(x_range=(-500,500), y_range=(-500,500), mesh_spacing=20.0, max_time=8640.0) – configure domain, options and output for a common simulation.
  • add_simple_substrate(name, diffusion_coeff=1000.0, decay_rate=0.1, initial_value=0.0) – quick helper to create a substrate with basic parameters.
  • add_simple_cell_type(name, secretion_substrate=None, secretion_rate=0.0, motile=False) – add a cell type with optional secretion and motility settings.
  • generate_xml() – assemble the XML tree for the current configuration and return it as a string.
  • save_xml(filename) – generate and write the XML to disk.
  • get_summary() – return a dictionary summarizing domain, substrates, cell types and options.
  • validate() – basic sanity checks returning a list of issues found.
  • legacy helpers set_domain, add_substrate, add_cell_type mirror module methods.
  • set_parallel_settings(omp_num_threads=4) – set OpenMP thread count.

Modules

The builder is composed of several modules located under physicell_config/modules. Each module exposes a small API focused on a single aspect of the configuration.

DomainModule

  • set_bounds(x_min, x_max, y_min, y_max, z_min=-10.0, z_max=10.0) – set the simulation domain limits.
  • set_mesh(dx, dy, dz=20.0) – mesh spacing in each dimension.
  • set_2D(use_2D=True) – toggle 2‑D mode.
  • add_to_xml(parent) – append domain settings to an XML element.
  • get_info() – return the currently stored domain values.

SubstrateModule

  • set_track_internalized_substrates(enabled) – include internalized substrate tracking flag.
  • add_substrate(name, diffusion_coefficient=1000.0, decay_rate=0.1, initial_condition=0.0, dirichlet_enabled=False, dirichlet_value=0.0, units='dimensionless', initial_units='mmHg') – register a new substrate and its physical parameters.
  • set_dirichlet_boundary(substrate_name, boundary, enabled, value=0.0) – configure boundary conditions per face.
  • remove_substrate(name) – delete a substrate definition.
  • add_to_xml(parent) – write microenvironment data to XML.
  • get_substrates() – return the internal dictionary of substrates.

CellTypeModule

Handles phenotype and behavioral properties for all cell types. - add_cell_type(name, parent_type='default', template='default') – create a cell type using a predefined template. - Numerous setter helpers exist for cycle model, death rates, volume, motility, secretion and intracellular models (see source for full list). - update_all_cell_types_for_substrates() – ensure secretion parameters exist for all substrates. - add_to_xml(parent) – serialize all cell type definitions to XML. - get_cell_types() – return the stored cell type definitions.

CellRulesModule

  • add_ruleset(name, folder='./config', filename='rules.csv', enabled=True) – declare a CSV ruleset to load during simulation.
  • add_rule(cell_type, signal, direction, behavior, saturation_value=0.0, half_max=0.5, hill_power=4.0, apply_to_dead=0) – add a rule following the CBHG v3.0 CSV format.
  • load_rules_from_csv(filename) / save_rules_to_csv(filename) – import or export rules in headerless PhysiCell CSV format.
  • generate_csv(filename) – alias for save_rules_to_csv that also prints a confirmation and returns the filename.
  • remove_rule(index) – delete a rule by zero-based index.
  • validate_rules() – validate all stored rules against the registry; returns a list of warning messages.
  • update_context_from_config(config) – sync available cell types and substrates from a config instance.
  • get_available_signals(filter_by_type=None) / get_available_behaviors(filter_by_type=None) – list known signals or behaviors, optionally filtered by type.
  • get_signal_by_name(name) / get_behavior_by_name(name) – look up a signal or behavior by human-readable name.
  • get_context() – return current context (cell types, substrates, custom variables).
  • add_to_xml(parent) – write the cell rules structure to XML.
  • get_rules() / get_rulesets() – return defined rules and rulesets.
  • clear_rules() / clear_rulesets() – reset rules or rulesets.
  • print_available_signals(filter_by_type=None) / print_available_behaviors(filter_by_type=None) – print signals or behaviors table.
  • print_context() – display current context.
  • print_rules() – display the rule list.

OptionsModule

  • set_max_time(max_time, units='min') – total simulation time.
  • set_time_steps(dt_diffusion=None, dt_mechanics=None, dt_phenotype=None) – adjust internal time steps.
  • set_virtual_wall(enabled) and other toggles like set_automated_spring_adhesions, set_random_seed, set_parallel_threads.
  • add_to_xml(parent) – append options to XML.
  • get_options() – return the stored options dictionary.

InitialConditionsModule

  • add_cell_cluster(cell_type, x, y, z=0.0, radius=100.0, num_cells=100) – place a sphere of cells.
  • add_single_cell(cell_type, x, y, z=0.0) – place a single cell.
  • add_rectangular_region(cell_type, x_min, x_max, y_min, y_max, z_min=-5.0, z_max=5.0, density=0.8) – fill a region with random cells.
  • add_csv_file(filename, folder='./config', enabled=False) – use an external CSV for initial positions.
  • add_to_xml(parent) – write initial conditions to XML.
  • get_conditions() – return the defined conditions.

SaveOptionsModule

  • set_output_folder(folder) – output path for simulation results.
  • set_full_data_options(interval=None, enable=None, settings_interval=None) – configure full data output.
  • set_svg_options(interval=None, enable=None) and set_svg_plot_substrate(enabled=False, limits=False, substrate='substrate', colormap='YlOrRd', min_conc=0, max_conc=1) for visualisation.
  • set_svg_legend(enabled=False, cell_phase=False, cell_type=True) – legend options.
  • set_legacy_data(enable) – toggle legacy format output.
  • add_to_xml(parent) – append save configuration.
  • get_save_options() – return internal save options.

PhysiBoSSModule

  • enable_physiboss(model_file='boolean_model.bnd', initial_values=None, mutations=None, parameters=None) – activate PhysiBoSS integration with initial settings.
  • set_time_step(value) and set_scaling(value) – adjust simulation step and scaling.
  • add_initial_value(node, value) / add_mutation(cell_line, node, value) / add_parameter(name, value) – modify network settings.
  • add_to_xml(parent) – serialize PhysiBoSS configuration when enabled.
  • is_enabled() – check status.
  • get_settings() – retrieve current options.

ConfigLoader

Utility singleton in physicell_config/modules/config_loader.py used by all modules to pull default parameters from JSON files.

  • get_cycle_model(name) – return cycle model templates
  • get_death_model(name) – apoptosis or necrosis defaults
  • get_volume_defaults() / get_mechanics_defaults() / get_motility_defaults() – phenotype defaults
  • get_cell_type_template(template_name) – load cell type presets
  • Built-in cell type templates: default, live_cell, maboss_cell
  • get_substrate_defaults(name) – standard substrate parameters

See docs/AdvancedFeatures.md for more details on advanced usage.

Detailed Module Functions

Below is a complete list of public helpers available in each module.

DomainModule

  • set_bounds(x_min, x_max, y_min, y_max, z_min=-10.0, z_max=10.0) – define the spatial extents of the domain.
  • set_mesh(dx, dy, dz=20.0) – specify grid spacing in microns.
  • set_2D(use_2D=True) – enable 2‑D simulations.
  • add_to_xml(parent) – append domain settings to an XML element.
  • get_info() – return current configuration as a dictionary.

SubstrateModule

  • set_track_internalized_substrates(enabled) – toggle tracking of internalised substrates.
  • add_substrate(name, diffusion_coefficient=1000.0, decay_rate=0.1, initial_condition=0.0, dirichlet_enabled=False, dirichlet_value=0.0, units='dimensionless', initial_units='mmHg') – create a substrate definition.
  • set_dirichlet_boundary(substrate_name, boundary, enabled, value=0.0) – set per‑face Dirichlet conditions.
  • remove_substrate(name) – delete an existing substrate.
  • add_to_xml(parent) – write microenvironment data to XML.
  • get_substrates() – return all defined substrates.

CellTypeModule

  • add_cell_type(name, parent_type='default', template='default') – create a new cell type from a template.
  • set_cycle_model(cell_type, model) – assign a cycle model (Ki67_basic, Ki67_advanced, live, cycling_quiescent, flow_cytometry, flow_cytometry_separated).
  • set_cycle_transition_rate(cell_type, from_phase, to_phase, rate) – override a specific phase transition rate.
  • set_cycle_phase_durations(cell_type, durations) – set cycle phase durations as a list of {index, duration, fixed_duration} dicts; clears any transition rates so <phase_durations> is used in the XML output. Both formats are valid in PhysiCell.
  • set_death_rate(cell_type, death_type, rate) – set the base death rate for 'apoptosis' or 'necrosis'.
  • set_death_parameters(cell_type, death_type, **params) – set death model sub-parameters: unlysed_fluid_change_rate, lysed_fluid_change_rate, cytoplasmic_biomass_change_rate, nuclear_biomass_change_rate, calcification_rate, relative_rupture_volume.
  • set_death_phase_durations(cell_type, death_type, durations) – set death phase durations; removes any existing phase_transition_rates.
  • set_death_phase_transition_rates(cell_type, death_type, rates) – set death phase transition rates as a list of {start_index, end_index, rate, fixed_duration} dicts; removes any existing phase_durations.
  • set_volume_parameters(cell_type, total=None, nuclear=None, fluid_fraction=None) – adjust volume attributes.
  • set_motility(cell_type, speed=None, persistence_time=None, migration_bias=None, enabled=None) – configure motility.
  • set_chemotaxis(cell_type, substrate, enabled=True, direction=1) – simple chemotaxis towards a substrate.
  • set_advanced_chemotaxis(cell_type, substrate_sensitivities, enabled=True, normalize_each_gradient=False) – multi‑substrate chemotaxis.
  • add_secretion(cell_type, substrate, secretion_rate, secretion_target=1.0, uptake_rate=0.0, net_export_rate=0.0) – add secretion parameters.
  • update_all_cell_types_for_substrates() – ensure secretion parameters exist for all substrates.
  • set_cell_adhesion_affinities(cell_type, affinities) – set per-cell-type adhesion affinities from a {target_name: value} dict; replaces any existing affinities.
  • update_all_cell_types_for_adhesion_affinities(default_affinity=1.0) – populate adhesion affinities so every cell type has an explicit entry for every other; preserves existing non-default values.
  • set_phagocytosis_rates(cell_type, apoptotic=None, necrotic=None, other_dead=None) – set dead-cell phagocytosis rates.
  • set_attack_rate(cell_type, target_cell_type, rate) – set the rate at which cell_type attacks target_cell_type.
  • set_attack_parameters(cell_type, damage_rate=None, duration=None) – set attack damage rate and duration.
  • set_transformation_rate(cell_type, target_cell_type, rate) – set the rate at which cell_type transforms into target_cell_type.
  • set_mechanics_parameters(cell_type, **params) – set any combination of mechanics parameters: cell_cell_adhesion_strength, cell_cell_repulsion_strength, relative_maximum_adhesion_distance, attachment_elastic_constant, attachment_rate, detachment_rate, maximum_number_of_attachments.
  • set_custom_data(cell_type, key, value, units='dimensionless', description='', conserved=False) – add or update a custom data entry.
  • clear_custom_data(cell_type) – remove all custom data entries for a cell type.
  • update_all_cell_types_for_interactions() – populate live phagocytosis, attack, fusion, and transformation rate dicts for all defined cell types with zero defaults.
  • add_intracellular_model(cell_type, model_type='maboss', bnd_filename='', cfg_filename='') – attach an intracellular model.
  • set_intracellular_settings(cell_type, intracellular_dt=None, time_stochasticity=None, scaling=None, start_time=None, inheritance_global=None) – tweak intracellular options.
  • add_intracellular_mutation(cell_type, intracellular_name, value) – force a node value.
  • add_intracellular_initial_value(cell_type, intracellular_name, value) – set initial node value.
  • add_intracellular_input(cell_type, physicell_name, intracellular_name, action='activation', threshold=1, smoothing=0) – map a substrate or variable to a network node.
  • add_intracellular_output(cell_type, physicell_name, intracellular_name, action='activation', value=1000000, base_value=0, smoothing=0) – map a network node to a behavior.
  • add_to_xml(parent) – serialize cell definitions to XML.
  • get_cell_types() – return all stored cell type data.

CellRulesModule

  • add_ruleset(name, folder='./config', filename='rules.csv', enabled=True) – register a CSV ruleset file.
  • add_rule(cell_type, signal, direction, behavior, saturation_value=0.0, half_max=0.5, hill_power=4.0, apply_to_dead=0) – store a rule following the CBHG v3.0 format.
  • load_rules_from_csv(filename) – import rules from a headerless PhysiCell CSV.
  • save_rules_to_csv(filename) – export current rules to a headerless PhysiCell CSV.
  • generate_csv(filename) – alias for save_rules_to_csv that also prints a confirmation and returns the filename.
  • remove_rule(index) – delete a rule by zero-based index.
  • validate_rules() – return warnings or errors for the current rule set.
  • update_context_from_config(config) – refresh cell types and substrates from a config instance.
  • get_available_signals(filter_by_type=None) – list known signals.
  • get_available_behaviors(filter_by_type=None) – list known behaviors.
  • get_context() – inspect current context.
  • get_signal_by_name(signal_name) – look up a signal by name.
  • get_behavior_by_name(behavior_name) – look up a behavior by name.
  • add_to_xml(parent) – write the cell rules section.
  • get_rules() – list rule dictionaries.
  • get_rulesets() – list registered rulesets.
  • clear_rules() – remove all rules.
  • clear_rulesets() – remove all rulesets.
  • print_available_signals(filter_by_type=None) – print signals table.
  • print_available_behaviors(filter_by_type=None) – print behaviors table.
  • print_context() – display current context.
  • print_rules() – display the rule list.

OptionsModule

  • set_max_time(max_time, units='min') – simulation duration.
  • set_time_steps(dt_diffusion=None, dt_mechanics=None, dt_phenotype=None) – override solver time steps.
  • set_virtual_wall(enabled) – toggle boundary walls.
  • set_automated_spring_adhesions(disabled) – disable automated adhesions.
  • set_random_seed(seed) – RNG seed.
  • set_legacy_random_points(enabled) – use legacy division points.
  • set_parallel_threads(num_threads) – OpenMP thread count.
  • add_to_xml(parent) – append options to XML.
  • get_options() – retrieve the options dictionary.

InitialConditionsModule

  • add_cell_cluster(cell_type, x, y, z=0.0, radius=100.0, num_cells=100) – place a spherical cluster.
  • add_single_cell(cell_type, x, y, z=0.0) – place one cell.
  • add_rectangular_region(cell_type, x_min, x_max, y_min, y_max, z_min=-5.0, z_max=5.0, density=0.8) – populate a region.
  • add_csv_file(filename, folder='./config', enabled=False) – import positions from CSV.
  • add_to_xml(parent) – write initial conditions to XML.
  • get_conditions() – return configured conditions.
  • clear_conditions() – remove all conditions.

SaveOptionsModule

  • set_output_folder(folder) – output directory.
  • set_full_data_options(interval=None, enable=None, settings_interval=None) – full data dump settings.
  • set_svg_options(interval=None, enable=None) – global SVG settings.
  • set_svg_plot_substrate(enabled=False, limits=False, substrate='substrate', colormap='YlOrRd', min_conc=0, max_conc=1) – substrate plot control.
  • set_svg_legend(enabled=False, cell_phase=False, cell_type=True) – legend visibility.
  • set_legacy_data(enable) – legacy output files.
  • add_to_xml(parent) – append save configuration.
  • get_save_options() – return save options.

PhysiBoSSModule

  • enable_physiboss(model_file='boolean_model.bnd', initial_values=None, mutations=None, parameters=None) – activate the Boolean network.
  • set_time_step(value) – network step size in minutes.
  • set_scaling(value) – scale network speed.
  • add_initial_value(node, value) – set a node's initial state.
  • add_mutation(cell_line, node, value) – force a mutation for a cell line.
  • add_parameter(name, value) – additional simulator parameter.
  • add_to_xml(parent) – export settings if enabled.
  • is_enabled() – check whether PhysiBoSS is active.
  • get_settings() – retrieve current PhysiBoSS options.

ConfigLoader

  • get_cycle_model(name)
  • get_death_model(name)
  • get_volume_defaults()
  • get_mechanics_defaults()
  • get_motility_defaults()
  • get_secretion_defaults()
  • get_cell_interactions_defaults()
  • get_cell_transformations_defaults()
  • get_cell_integrity_defaults()
  • get_custom_data_defaults(data_type='sample')
  • get_initial_parameter_distributions_defaults()
  • get_intracellular_defaults(intracellular_type='maboss')
  • get_cell_type_template(template_name)
  • get_substrate_defaults(name='substrate')
  • get_default_phenotype(template='default')

Package Weaknesses and Possible Improvements

While the package offers a comprehensive API, several aspects could be enhanced:

  1. Sparse documentation for advanced features – some complex methods lack detailed examples. Extended tutorials and docstrings would ease adoption.
  2. Validation gaps – configuration validation currently checks only a few conditions. More thorough checks (e.g. verifying cross‑module consistency) can prevent runtime errors.
  3. No explicit versioned schema – the XML generation assumes a single schema. Providing version compatibility layers or schema definitions would help long‑term maintenance.
  4. Dependency on large JSON defaults – modifying default parameters requires editing JSON files manually. A helper API for managing these defaults could simplify customization.

Addressing these items would make the project more robust and easier to extend.