BioDynaMo  v1.03.56-8762fa70
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
double simulation_time_step = 0.01
double simulation_max_displacement = 3.0
BoundSpaceMode bound_space = kOpen
double min_bound = 0
double 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
double 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 34 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 195 of file param.h.

◆ ExecutionOrder


Definition at line 436 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 102 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 270 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 69 of file param.h.

◆ Get() [2/2]

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

Definition at line 58 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 158 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 176 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 217 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 477 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 262 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 467 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 243 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 254 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 121 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 454 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 309 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 301 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

double 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 235 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

double 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

double 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 226 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 double 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 130 of file param.h.

◆ numerical_ode_solver

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

Definition at line 103 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 112 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 325 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 340 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 89 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 148 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 168 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 317 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 434 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

double 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 193 of file param.h.

◆ simulation_time_step

double 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 184 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 278 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 139 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 98 of file param.h.

◆ use_bdm_mem_mgr

bool bdm::Param::use_bdm_mem_mgr = true

Use the BioDynaMo memory manager. 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 424 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 290 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 359 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 350 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 383 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 413 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