readme.txt 7.64 KB
Newer Older
gsaxena's avatar
gsaxena committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
BioFVM_X is based on BioFVM v 1.1.6. 

+ BioFVM (http://BioFVM.MathCancer.org) supports only on-node shared memory 
  parallelism using OpenMP.

+ BioFVM_X adds MPI to BioFVM to parallelize the core kernels of BioFVM using  
  MPI.

+ Some core kernels are: Domain Partitioning, Basic Agent Generation, Gaussian 
  Profile building, File Writing, Direct Solver (Thomas).
  
+ Most of the MPI-based parallel functions are made available in 
  BioFVM_parallel.cpp
  
+ A Makefile is given and a sample example in ./examples/tutorial1_BioFVM.cpp 
  is completely parallelized using MPI + OpenMP. 
  
+ Procedure to run:
gsaxena's avatar
gsaxena committed
19 20 21 22 23 24 25
  (1) git clone the repository
  (2) Change to the top level directory i.e. $ cd GS_BioFVM_X/GS_BioFVM
  (3) Make sure GCC 8.1 (or other version) and OpenMPI 3.1.1 (or other version) 
      present (or the modules are loaded in a module environment)
  (4) Execute $ make tutorial1
      This results in an executable file "tutorial1" in the directory ./examples
  (5)  For the SLURM scheduler, the following script can be used:
gsaxena's avatar
gsaxena committed
26
 
gsaxena's avatar
gsaxena committed
27
============================================================================
gsaxena's avatar
gsaxena committed
28 29 30 31 32 33 34 35 36 37 38 39 40 41
 #!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=2
#SBATCH --cpus-per-task=24
#SBATCH -t 00:15:00
#SBATCH -o output-%j
#SBATCH -e error-%j
#SBATCH --exclusive

export OMP_DISPLAY_ENV=true
export OMP_NUM_THREADS=24
export OMP_PROC_BIND=spread
export OMP_PLACES=threads
mpiexec --map-by ppr:1:socket:pe=24  --report-bindings ./examples/tutorial1
gsaxena's avatar
gsaxena committed
42
============================================================================
gsaxena's avatar
gsaxena committed
43

gsaxena's avatar
gsaxena committed
44
This script implies :
gsaxena's avatar
gsaxena committed
45

gsaxena's avatar
gsaxena committed
46 47 48 49 50
(1) uses 1 single node 
(2) spawns 2 MPI processes in that node (Since we have 2 sockets per node, we 
    create 2 MPI processes i.e. 1 MPI process per socket).
(3) create 24 threads per MPI process  (Since we have 24 cores in 1 socket,
    we create 24 threads i.e. 1 thread per core).
gsaxena's avatar
gsaxena committed
51

gsaxena's avatar
gsaxena committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
IMPORTANT: 

(a) Please make sure that the dimension of the Physical domain 
(specified by the constant 'N' in ./examples/tutorial1_BioFVM.cpp) 
is completely divisible by the Voxel dimensions (given by 
mesh_resolution in ./examples/tutorial1_BioFVM.cpp).

(b) Please make sure that the number of Voxels in the X direction are perfectly 
divisible by the total number of processes. 

For the given example: N=1000, minX=0, maxX=N, mesh_resolution=10. This gives 
total Voxels in X (or Y or Z) direction as (maxX-minX)/mesh_resolution = 
(1000 - 0)/10 = 100 Voxels. Now the total number of Voxels in the X-direction 
must be perfectly divisible by total number of MPI processes (in this case P=2).
Thus, we have 100/2 = 50 Voxels per process. 
gsaxena's avatar
gsaxena committed
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205


BioFVM: Finite Volume Solver for Biological Problems. 

Version:      1.1.6
Release date: 19 August 2017

Homepage:     http://BioFVM.MathCancer.org
Downloads:    http://BioFVM.sf.net

Summary:  
This update includes small bug fixes and enhancements for 
compatibiltiy with PhysiCell. It is focused on improving 
its handling of default settings and Dirichlet conditions. 

New features:
+ Added ability to enable / disable Dirichlet conditions for 
  individual substrates. Use: 
  
  void Microenvironment::set_substrate_dirichlet_activation(
       int substrate_index , bool new_value )
  
  to set substrate with index substrate_index to apply or 
  not apply Dirichlet conditions, for all defined Dirichlet 
  nodes. (e.g., you want to set Dirichlet conditions for the
  first substrate, but not teh others). 
  
+ Added Boolean new use_oxygen_as_first_field to Microenvironment_Options,
  so that initialize_microenvironment() only uses these if the flag 
  is set to true. By default, it is set to true. 
  
+ Calling "Microenvironment.set_density()" or 
  "Microenvironment.add_density()" now sets: 
  
  default_microenvironment_options.use_oxygen_as_first_field = false
  
  so that calling initialize_microenvironment() after defining fields 
  does not overwrite prior user choices. 
  
  These functions also correctly resize 
  
  default_microenvironment_options.Dirichlet_condition_vector and 
  default_microenvironment_options.Dirichlet_activation_vector
  
+ Updated all the add/update_density functions in the Mircoenvironment,
  so that adding a new density sets   
  
+ Updated Microenvironment::apply_dirichlet_conditions() so that 
  it only applies to the substrates j for which 
  
  microenvironment.dirichlet_activation_vector[j] == true 

Bugfixes: 
+ Fixed initialize_microenvironment() so that it now only applies Dirichlet 
  conditions if 
  
  default_microenvironment_options.outer_Dirichlet_conditions == true 
  
+ Updated the makefiles to use ARCH := native, which simplifies setup. 
  This generally has your compiler query your processor for available 
  hardware optimizations, so you don't have to choose this yourself 
  (e.g., ARCH := haswell). I suggest using a compiler at least as 
  recent as gcc/g++ 6.5.x   
  
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  
Version:      1.1.5
Release date: 19 July 2017

Homepage:     http://BioFVM.MathCancer.org
Downloads:    http://BioFVM.sf.net

Summary:  
This update includes small bug fixes and enhancements for 
compatibiltiy with PhysiCell. 

New features:
+ Added Microenvironment::find_substrate_index( std::string ) to make it 
  easier to find . 
  
+ Added Basic_Agent::nearest_gradient( int substrate_index ) to directly 
  access the gradient of the indicated substrate at the agent's  
  current_voxel_index. 
  
+ Added Basic_Agent::nearest_gradient_vector( void ) to directly 
  access a vector of gradients (one for each substrate in the 
  microenvironment) at the agent's current_voxel_index. 
 
+ Added Microenvironment::is_dirichlet_node( int voxel_index ) to 
  easily check if the voxel is a Dirichlet node. 
  
+ Added new class Microenvironment_Options, with a default 
  default_microenvironment_options, to simplify Microenvironment
  setup. The defaults are dx = dy = dz = 20 microns, on 1 cubic mm. 
  
+ Added function initialize_microenvironment() to set up the 
  microenvironment using the options in 
  default_microenvironment_options. The code sets oxygen as the 
  default field, with D = 1e5 micron^2/min, and decay rate = 0.1 1/min
  (a 1 mm diffusion length scale). If 
  default_microenvironment_options.outer_Dirichlet_conditions = true, 
  then we set a 38 mmHg condition on the outer edges, corresponding to
  5% oxygenation (physioxic conditions). 

+ Updated the makefile to default to MARCH := native, which allows
  automated performance tuning without user editing of the Makefile.

Bugfixes: 
+ correct typos in citation information in all source files 

+ updated citation information 

+ added void set_default_microenvironment( Microenvironment* M ) declaration to 
  BioFVM_Microenvironment.h
 
+ set volume_is_changed = false in Basic_Agent::set_internal_uptake_constants(); 

+ Set the MultiCellDS options Booleans to extern bool in BioFVM_MultiCellDS.h 
  so that PhysiCell can read these options. 

+ Updated the simlified_data field in MultiCellDS XML output to include a 
  new "source" attribute with value "BioFVM".

+ Updated Microenvironment::update_dirichlet_node() and 
  Microenvironment::remove_dirichlet_node() to check against 
  mesh.voxels[].is_Dirichlet to provide a cheap and early exit 
  if the node isn't Dirichlet in the first place. 
  
+ Changed to a thread-safe data structure for Dirichlet nodes 
  (e.g., if a custom cell function in an OMP loop adds or removes 
  Dirichlet nodes). 
  
+ Fixed convergence_test3.cpp, convergence_test4_1.cpp, 
  convergence_test4_2.cpp, convergence_test5.cpp, 
  performance_test_numcells.cpp, tutorial1_BioFVM.cpp, 
  and main_experiment.cpp to use Basic_Agent::set_total_volume(). 

+ Fixed tutorial3_BioFVM.cpp to use dirichlet_one instead of 
  dirichlet_zero.