BioDynaMo  v1.05.0-137fdb15
Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Private Member Functions | Private Attributes | Static Private Attributes | Friends | List of all members
bdm::Param Struct Reference

#include <param.h>

Collaboration diagram for bdm::Param:


struct  VisualizeDiffusion

Public Types

enum  NumericalODESolver { kEuler = 1, kRK4 = 2 }
enum  BoundSpaceMode { kOpen = 0, kClosed, kTorus }
enum  ThreadSafetyMechanism { kNone = 0, kUserSpecified, kAutomatic }
enum  ExecutionOrder { kForEachAgentForEachOp = 0, kForEachOpForEachAgent }
enum  MappedDataArrayMode { kZeroCopy = 0, kCopy, kCache }

Public Member Functions

 Param ()
 ~Param ()
 Param (const Param &other)
void Restore (Param &&other)
std::string ToJsonString () const
void MergeJsonPatch (const std::string &patch)
template<typename TParamGroup >
const TParamGroup * Get () const
template<typename TParamGroup >
TParamGroup * Get ()
void AssignFromConfig (const std::shared_ptr< cpptoml::table > &)
 Assign values from config file to variables. More...

Static Public Member Functions

static void RegisterParamGroup (ParamGroup *param)

Public Attributes

uint64_t random_seed = 4357
std::vector< std::string > unschedule_default_operations
NumericalODESolver numerical_ode_solver = NumericalODESolver::kEuler
std::string output_dir = "output"
std::string environment = "uniform_grid"
uint32_t nanoflann_depth = 10
uint32_t unibn_bucketsize = 16
bool remove_output_dir_contents = true
std::string backup_file = ""
std::string restore_file = ""
uint32_t backup_interval = 1800
real_t simulation_time_step = 0.01
real_t simulation_max_displacement = 3.0
BoundSpaceMode bound_space = kOpen
real_t min_bound = 0
real_t max_bound = 100
std::string diffusion_boundary_condition = "open"
std::string diffusion_method = "euler"
bool calculate_gradients = true
ThreadSafetyMechanism thread_safety_mechanism
std::string visualization_engine = "paraview"
bool insitu_visualization = false
bool export_visualization = false
bool root_visualization = false
std::string pv_insitu_pipeline
std::string pv_insitu_pipelinearguments = ""
uint32_t visualization_interval = 1
bool visualization_export_generate_pvsm = true
std::map< std::string, std::set< std::string > > visualize_agents
 JSON_object. More...
std::vector< VisualizeDiffusionvisualize_diffusion
bool visualization_compress_pv_files = true
uint64_t scheduling_batch_size = 1000
ExecutionOrder execution_order = ExecutionOrder::kForEachAgentForEachOp
bool detect_static_agents = false
bool cache_neighbors = false
bool use_bdm_mem_mgr = true
uint64_t mem_mgr_aligned_pages_shift = 5
real_t mem_mgr_growth_rate = 1.1
uint64_t mem_mgr_max_mem_per_thread_factor = 1
bool minimize_memory_while_rebalancing = true
Param::MappedDataArrayMode mapped_data_array_mode
bool statistics = false
bool debug_numa = false
uint64_t show_simulation_step = 0
bool use_progress_bar = false
std::string compute_target = "cpu"
bool opencl_debug = false
int preferred_gpu = 0
bool plot_memory_layout = false

Private Member Functions

 BDM_CLASS_DEF_NV (Param, 1)

Private Attributes

std::unordered_map< ParamGroupUid, ParamGroup * > groups_

Static Private Attributes

static std::unordered_map< ParamGroupUid, std::unique_ptr< ParamGroup > > registered_groups_


class DiffusionTest_CopyOldData_Test

Detailed Description

Definition at line 35 of file param.h.

Member Enumeration Documentation

◆ BoundSpaceMode


The simulation space grows to encapsulate all agents.


Enforce an artificial cubic bound around the simulation space. The dimensions of this cube are determined by parameter min_bound and max_bound.
If agents move outside the cube they are moved back inside.


Enforce an artificial cubic bound around the simulation space. The dimensions of this cube are determined by parameter min_bound and max_bound.
Agents that move outside the cube are moved back in on the opposite side.

Definition at line 196 of file param.h.

◆ ExecutionOrder


Definition at line 437 of file param.h.

◆ MappedDataArrayMode

MappedDataArrayMode options: kZeroCopy: access agent data directly only if it is requested.
kCache: Like kZeroCopy but stores the results in contigous array, to speed up access if it is used again.
kCopy: Copy all data elements to a contigous array at initialization time. Serves requests from the cache.


Definition at line 543 of file param.h.

◆ NumericalODESolver

Variable which specifies method using for solving differential equation {"Euler", "RK4"}.


Definition at line 103 of file param.h.

◆ ThreadSafetyMechanism

List of thread-safety mechanisms
kUserSpecified: The user has to define all agent that must not be processed in parallel.

See also
kAutomatic: The simulation automatically locks all agents of the microenvironment.

Definition at line 271 of file param.h.

Constructor & Destructor Documentation

◆ Param() [1/2]

bdm::Param::Param ( )

Definition at line 42 of file

◆ ~Param()

bdm::Param::~Param ( )

Definition at line 50 of file

◆ Param() [2/2]

bdm::Param::Param ( const Param other)

Definition at line 65 of file

Member Function Documentation

◆ AssignFromConfig()

void bdm::Param::AssignFromConfig ( const std::shared_ptr< cpptoml::table > &  config)

Assign values from config file to variables.

Definition at line 220 of file


bdm::Param::BDM_CLASS_DEF_NV ( Param  ,

◆ Get() [1/2]

template<typename TParamGroup >
TParamGroup* bdm::Param::Get ( )

Definition at line 70 of file param.h.

◆ Get() [2/2]

template<typename TParamGroup >
const TParamGroup* bdm::Param::Get ( ) const

Definition at line 59 of file param.h.

◆ MergeJsonPatch()

void bdm::Param::MergeJsonPatch ( const std::string &  patch)

Applies a JSON merge patch ( to this parameter and ParamGroupeter. The groups_ data member must be flattened. See output of ToJsonString().

Definition at line 126 of file

◆ RegisterParamGroup()

void bdm::Param::RegisterParamGroup ( ParamGroup param)

Definition at line 37 of file

◆ Restore()

void bdm::Param::Restore ( Param &&  other)

Definition at line 57 of file

◆ ToJsonString()

std::string bdm::Param::ToJsonString ( ) const

Returns a Json representation of this parameter and all ParamGroupeter. The groups_ data member has been flattened to simplify JSON merge patches (

Definition at line 108 of file

Friends And Related Function Documentation

◆ DiffusionTest_CopyOldData_Test

friend class DiffusionTest_CopyOldData_Test

Definition at line 632 of file param.h.

Member Data Documentation

◆ backup_file

std::string bdm::Param::backup_file = ""

Backup file name for full simulation backups
Path is relative to working directory.
Default value: "" (no backups will be made)
TOML config file:

backup_file = <path>/<filename>.root

Command line argument: -b, --backup

Definition at line 159 of file param.h.

◆ backup_interval

uint32_t bdm::Param::backup_interval = 1800

Specifies the interval (in seconds) in which backups will be performed.
Default Value: 1800 (every half an hour)
TOML config file:

backup_interval = 1800  # backup every half an hour 

Definition at line 177 of file param.h.

◆ bound_space

BoundSpaceMode bdm::Param::bound_space = kOpen

Default value: open (simulation space is "infinite")

See also
BoundSpaceMode TOML config file:
bound_space = "open" 

Definition at line 218 of file param.h.

◆ cache_neighbors

bool bdm::Param::cache_neighbors = false

Neighbors of an agent can be cached so to avoid consecutive searches. This of course only makes sense if there is more than one ForEachNeighbor* operation.
Default value: false
TOML config file:

cache_neighbors = false 

Definition at line 478 of file param.h.

◆ calculate_gradients

bool bdm::Param::calculate_gradients = true

Calculate the diffusion gradient for each substance.
TOML config file: Default value: true

calculate_gradients = true 

Definition at line 263 of file param.h.

◆ compute_target

std::string bdm::Param::compute_target = "cpu"

Run the simulation partially on the GPU for improved performance. Possible values: "cpu", "cuda", "opencl" Default value: "cpu"
TOML config file: [experimental] compute_target = false

Definition at line 607 of file param.h.

◆ debug_numa

bool bdm::Param::debug_numa = false

Output debugging info related to running on NUMA architecture.

See also
ThreadInfo, ResourceManager::DebugNuma Default Value: false
TOML config file:
debug_numa = false 

Definition at line 575 of file param.h.

◆ detect_static_agents

bool bdm::Param::detect_static_agents = false

Calculation of the displacement (mechanical interaction) is an expensive operation. If agents do not move or grow, displacement calculation is ommited if detect_static_agents is turned on. However, the detection mechanism introduces an overhead. For dynamic simulations where agents move and grow, the overhead outweighs the benefits.
Default value: false
TOML config file:

detect_static_agents = false 

Definition at line 468 of file param.h.

◆ diffusion_boundary_condition

std::string bdm::Param::diffusion_boundary_condition = "open"

Define the boundary condition of the diffusion grid [open, closed]
Default value: "open"
TOML config file:

diffusion_boundary_condition = "open" 

Definition at line 244 of file param.h.

◆ diffusion_method

std::string bdm::Param::diffusion_method = "euler"

A string for determining diffusion type within the simulation space. current inputs include "euler" and "runge-kutta". Default value: "euler"
TOML config file:

   diffusion_method = <diffusion method>

Definition at line 255 of file param.h.

◆ environment

std::string bdm::Param::environment = "uniform_grid"

The method used to query the environment of a simulation object. Default value: "uniform_grid"
Other allowed values: "kd_tree", "octree"
TOML config file:

environment = "uniform_grid" 

Definition at line 122 of file param.h.

◆ execution_order

ExecutionOrder bdm::Param::execution_order = ExecutionOrder::kForEachAgentForEachOp

This parameter determines whether to execute kForEachAgentForEachOp

for (auto* agent : agents) {
for (auto* op : agent_ops) {

or kForEachOpForEachAgent

for (auto* op : agent_ops) {
for (auto* agent : agents) {

Definition at line 455 of file param.h.

◆ export_visualization

bool bdm::Param::export_visualization = false

Write data to file for post-simulation visualization Default value: false
TOML config file:

export = false 

Definition at line 310 of file param.h.

◆ groups_

std::unordered_map<ParamGroupUid, ParamGroup*> bdm::Param::groups_

Definition at line 635 of file param.h.

◆ insitu_visualization

bool bdm::Param::insitu_visualization = false

Use ParaView Catalyst for insitu visualization.
Insitu visualization supports live visualization and rendering without writing files to the harddisk.
Default value: false
TOML config file:

insitu = false 

Definition at line 302 of file param.h.

◆ mapped_data_array_mode

Param::MappedDataArrayMode bdm::Param::mapped_data_array_mode
Initial value:

This parameter sets the operation mode in bdm::MappedDataArray.
Allowed values are defined in MappedDataArrayMode
Possible values: zero-copy, cache, copy
Default value: zero-copy
TOML config file:

mapped_data_array_mode = "zero-copy" 

Definition at line 553 of file param.h.

◆ max_bound

real_t bdm::Param::max_bound = 100

Maximum allowed value for x-, y- and z-position if simulation space is bound (

See also
Default value: 100
TOML config file:
max_bound = 100 

Definition at line 236 of file param.h.

◆ mem_mgr_aligned_pages_shift

uint64_t bdm::Param::mem_mgr_aligned_pages_shift = 5

The BioDynaMo memory manager allocates N page aligned memory blocks. The bigger N, the lower the memory overhead due to metadata storage if a lot of memory is used.
N must be a number of two.
Therefore, this parameter specifies the shift for N. N = 2 ^ shift
Default value: 5 -> N = 32
TOML config file:

mem_mgr_aligned_pages_shift = 5 

Definition at line 497 of file param.h.

◆ mem_mgr_growth_rate

real_t bdm::Param::mem_mgr_growth_rate = 1.1

The BioDynaMo memory manager allocates memory in increasing sizes using a geometric series. This parameter specifies the growth rate. Default value: 2.0
TOML config file:

mem_mgr_growth_rate = 1.1 

Definition at line 506 of file param.h.

◆ mem_mgr_max_mem_per_thread_factor

uint64_t bdm::Param::mem_mgr_max_mem_per_thread_factor = 1

The BioDynaMo memory manager can migrate memory between thread pools to avoid memory leaks.
This parameter influences the maximum memory size in bytes before migration happens.
The size in bytes depends on the system's page size and the parameter mem_mgr_aligned_pages_shift and is calculated as follows: PAGE_SIZE * 2 ^ mem_mgr_aligned_pages_shift * mem_mgr_max_mem_per_thread_factor
Default value: 1
TOML config file:

mem_mgr_max_mem_per_thread_factor = 1 

Definition at line 520 of file param.h.

◆ min_bound

real_t bdm::Param::min_bound = 0

Minimum allowed value for x-, y- and z-position if simulation space is bound (

See also
Default value: 0
TOML config file:
min_bound = 0 

Definition at line 227 of file param.h.

◆ minimize_memory_while_rebalancing

bool bdm::Param::minimize_memory_while_rebalancing = true

This parameter is used inside ResourceManager::LoadBalance. If it is set to true, the function will reuse existing memory to rebalance agents to NUMA nodes. (A small amount of additional memory is still required.)
If this parameter is set to false, the balancing function will first create new objects and delete the old ones in a second step. In the worst case this will real_t the required memory for agents for. Default value: true
TOML config file:

minimize_memory_while_rebalancing = true 

Definition at line 534 of file param.h.

◆ nanoflann_depth

uint32_t bdm::Param::nanoflann_depth = 10

The depth of the kd tree if it's set as the environment (see Param::environment). For more information see:
TOML config file:

nanoflann_depth = 10 

Definition at line 131 of file param.h.

◆ numerical_ode_solver

NumericalODESolver bdm::Param::numerical_ode_solver = NumericalODESolver::kEuler

Definition at line 104 of file param.h.

◆ opencl_debug

bool bdm::Param::opencl_debug = false

Compile OpenCL kernels with debugging symbols, for debugging on CPU targets with GNU gdb. Default value: false
TOML config file: [experimental] opencl_debug = false

Definition at line 615 of file param.h.

◆ output_dir

std::string bdm::Param::output_dir = "output"

Output Directory name used to store visualization and other files.
Path is relative to working directory.
Default value: "output"
TOML config file:

output_dir = "output" 

Definition at line 113 of file param.h.

◆ plot_memory_layout

bool bdm::Param::plot_memory_layout = false

Determines if agents' memory layout plots should be generated during load balancing.

Definition at line 626 of file param.h.

◆ preferred_gpu

int bdm::Param::preferred_gpu = 0

Set the index of the preferred GPU you wish to use. Default value: 0
TOML config file: [experimental] preferred_gpu = 0

Definition at line 622 of file param.h.

◆ pv_insitu_pipeline

std::string bdm::Param::pv_insitu_pipeline
Initial value:

Enable insitu visualization with a custom python pipeline Default value: "<path-to-bdm>/include/core/visualization/paraview/"
TOML config file: [visualization] pv_insitu_pipeline = ""

Definition at line 326 of file param.h.

◆ pv_insitu_pipelinearguments

std::string bdm::Param::pv_insitu_pipelinearguments = ""

Arguments that will be passed to the python ParaView insitu pipeline specified in Param::pv_insitu_pipeline.
The arguments will be passed to the ExtendDefaultPipeline function def ExtendDefaultPipeline(renderview, coprocessor, datadescription, script_args): as fourth argument.
Default value: ""
TOML config file:

pv_insitu_pipelinearguments = "" 

Definition at line 341 of file param.h.

◆ random_seed

uint64_t bdm::Param::random_seed = 4357

Set random number seed.
The pseudo random number generator (prng) of each thread will be initialized as follows: prng[tid].SetSeed(random_seed * (tid + 1));
Default value: 4357
TOML config file:

random_seed = 4357 

Definition at line 90 of file param.h.

◆ registered_groups_

std::unordered_map< ParamGroupUid, std::unique_ptr< ParamGroup > > bdm::Param::registered_groups_

Definition at line 634 of file param.h.

◆ remove_output_dir_contents

bool bdm::Param::remove_output_dir_contents = true

If set to true (default), BioDynaMo will automatically delete all contents inside Param::output_dir at the beginning of the simulation. Use with caution in combination with Param::output_dir. If you do not want to delete the content, set this parameter to false. BioDynaMo then organizes your simulation outputs in additional subfolders labelled with the date-time of your simulation YYYY-MM-DD-HH:MM:SS. Note that you will inevitably use more disk space with this option.

Definition at line 149 of file param.h.

◆ restore_file

std::string bdm::Param::restore_file = ""

File name to restore simulation from
Path is relative to working directory.
Default value: "" (no restore will be made)
TOML config file:

restore_file = <path>/<filename>.root

Command line argument: -r, --restore

Definition at line 169 of file param.h.

◆ root_visualization

bool bdm::Param::root_visualization = false

Use ROOT for enable visualization.
Default value: false
TOML config file:

root = false 

Definition at line 318 of file param.h.

◆ scheduling_batch_size

uint64_t bdm::Param::scheduling_batch_size = 1000

Batch size used by the Scheduler to iterate over agents
Default value: 1000
TOML config file:

scheduling_batch_size = 1000 

Definition at line 435 of file param.h.

◆ show_simulation_step

uint64_t bdm::Param::show_simulation_step = 0

Display the simulation step in the terminal output with a defined frequency.\nThe value 0 shows no output, a value of 1 prints all steps, a value of 2 prints every second step, and so on.
Default value: 0
TOML config file: [development] show_simulation_step = 0

Definition at line 584 of file param.h.

◆ simulation_max_displacement

real_t bdm::Param::simulation_max_displacement = 3.0

Maximum jump that a point mass can do in one time step. Useful to stabilize the simulation
Default value: 3.0
TOML config file:

max_displacement = 3.0 

Definition at line 194 of file param.h.

◆ simulation_time_step

real_t bdm::Param::simulation_time_step = 0.01

Time between two simulation steps, in hours. Default value: 0.01
TOML config file:

time_step = 0.0125 

Definition at line 185 of file param.h.

◆ statistics

bool bdm::Param::statistics = false

Statistics of profiling data; keeps track of the execution time of each operation at every timestep.
If set to true it prints simulation data at the end of the simulation to std::cout and a file.
Default Value: false
TOML config file:

statistics = false 

Definition at line 566 of file param.h.

◆ thread_safety_mechanism

ThreadSafetyMechanism bdm::Param::thread_safety_mechanism
Initial value:

Select the thread-safety mechanism.
Possible values are: none, user-specified, automatic.
TOML config file:

thread_safety_mechanism = "none" 

Definition at line 279 of file param.h.

◆ unibn_bucketsize

uint32_t bdm::Param::unibn_bucketsize = 16

The bucket size of the octree if it's set as the environment (see Param::environment). For more information see: TOML config file:

unibn_bucketsize = 16 

Definition at line 140 of file param.h.

◆ unschedule_default_operations

std::vector<std::string> bdm::Param::unschedule_default_operations

List of default operation names that should not be scheduled by default Default value: {}
TOML config file:

unschedule_default_operations = ["mechanical forces", "load

Definition at line 99 of file param.h.

◆ use_bdm_mem_mgr

bool bdm::Param::use_bdm_mem_mgr = true

Default value: true
TOML config file:

use_bdm_mem_mgr = true 

Definition at line 485 of file param.h.

◆ use_progress_bar

bool bdm::Param::use_progress_bar = false

Use a progress bar to visualize the simulation progress. The progress bar also gives an estimate of the remaining simulation time assuming that the following simulations steps are as computationally expensive as the previous ones. It is not recommended to use the ProgressBar when you write information to std::cout in Simulate() because the ProgressBar uses '\r' in its print statements. Default value: false
TOML config file: [development] use_progress_bar = false

Definition at line 596 of file param.h.

◆ visualization_compress_pv_files

bool bdm::Param::visualization_compress_pv_files = true

Specifies if the ParView files that are generated in export mode should be compressed.
Default value: true
TOML config file:

export = true
compress_pv_files = true

Definition at line 425 of file param.h.

◆ visualization_engine

std::string bdm::Param::visualization_engine = "paraview"

Name of the visualization engine to use for visualizaing BioDynaMo simulations
Default value: "paraview"
TOML config file:

adaptor = <name_of_adaptor> 

Definition at line 291 of file param.h.

◆ visualization_export_generate_pvsm

bool bdm::Param::visualization_export_generate_pvsm = true

If export_visualization is set to true, this parameter specifies if the ParaView pvsm file will be generated!
Default value: true
TOML config file:

export_generate_pvsm = true 

Definition at line 360 of file param.h.

◆ visualization_interval

uint32_t bdm::Param::visualization_interval = 1

If export_visualization is set to true, this parameter specifies how often it should be exported. 1 = every timestep, 10: every 10 time steps.
Default value: 1
TOML config file:

interval = 1 

Definition at line 351 of file param.h.

◆ visualize_agents

std::map<std::string, std::set<std::string> > bdm::Param::visualize_agents


Specifies which agents should be visualized.
Every agent defines the minimum set of data members which are required to visualize it. (e.g. Cell: position_ and diameter_).
With this parameter it is also possible to extend the number of data members that are sent to the visualization engine. Default value: empty (no agent will be visualized)
NB: This data member is not backed up, due to a ROOT error. TOML config file:

# turn on insitu or export
export = true

  name = "Cell"
  # the following entry is optional
  additional_data_members = [ "density_" ]

  # The former block can be repeated for further agents
  name = "Neurite" 

Definition at line 384 of file param.h.

◆ visualize_diffusion

std::vector<VisualizeDiffusion> bdm::Param::visualize_diffusion

Specifies for which substances extracellular diffusion should be visualized.
Default value: empty (no diffusion will be visualized)
TOML config file:

# turn on insitu or export
export = true

  # Name of the substance
  name = "Na"
  # the following two entries are optional
  #   default value for concentration is true
  concentration = true
  #   default value for gradient is false
  gradient = false

  # The former block can be repeated for further substances
  name = "K"
  # default values: concentration = true and gradient = false 

Definition at line 414 of file param.h.

The documentation for this struct was generated from the following files:
std::string Concat(const Args &... parts)
Concatenates all arguments into a string. Equivalent to streaming all arguments into a stringstream a...
Definition: string.h:70