Merge branch 'development' of https://github.com/MathCancer/PhysiCell into development

Author: MathCancer

BioFVM/BioFVM_basic_agent.h

@@ -73,11 +73,13 @@ class Basic_Agent
 	std::vector<double> cell_source_sink_solver_temp_export1; 
 	std::vector<double> cell_source_sink_solver_temp_export2; 	
 	std::vector<double> previous_velocity; 
-	bool is_active;
+//	bool is_active;
 
 	std::vector<double> total_extracellular_substrate_change; 
 
  public:
+	bool is_active;
+
 	std::vector<double> * secretion_rates; 
 	std::vector<double> * saturation_densities; 
 	std::vector<double> * uptake_rates;  

README.md

@@ -1,8 +1,8 @@
 # PhysiCell: an Open Source Physics-Based Cell Simulator for 3-D Multicellular Systems.
 
-**Version:** 1.7.0
+**Version:** 1.7.1
 
-**Release date:** 12 May 2020
+**Release date:** 2 June 2020
 
 ## Overview: 
 PhysiCell is a flexible open source framework for building agent-based multicellular models in 3-D tissue environments.
@@ -32,7 +32,7 @@ Visit http://MathCancer.org/blog for the latest tutorials and help.
     heterogeneity-sample
     cancer-immune-sample 
     virus-macrophage-sample
-    temlate 
+    template
 
 **make list-projects** : list all available sample projects 
 
@@ -62,158 +62,72 @@ See changes.md for the full change log.
 * * * 
 ## Release summary: 
 
-This release (1) adds "net export" as a new form of more generalized substrate secretion, (2) adds helper funtions for cell size and volume for esier configuration, (3) adds a new, standardized chemotaxis function, (4) adds 1D diffusion, and (5) introduces XML-based cell definitions as a beta feature. It also incorporates a variety of bugfixes.   
+This release introduces bug fixes (particularly the placement of daughter cells after division), introduces new functions for uniformly random sampling of the unit circle and unit sphere, and refines the beta implementation of XML-based cell definitions. 
 
 **NOTE:** OSX users must now define PHYSICELL_CPP system variable. See the documentation.
 
 ### Major new features and changes:
 
-+ Added "net_export_rates" to "secretion" part of Phenotype, and to the Basic_Agent class in BioFVM. This is in response to SourceForge ticket 19. 
-
-+ Added new helper functions to help users to more easily set the *target* cell size: 
-   + void Cell::set_target_volume( double new_volume ) sets the target total cell volume, while preserving the desired nuclear:cytoplasmic ratio and desired fluid fraction. In the default cell volume model, the cell will now approach this value by shrinking or growing. 
-   + void Cell::set_target_radius( double new_radius ) behaves similarly, but using a radius instead. 
-
-+ Added Cell::set_radius( double new_radius ) to set the cell's current radius to the new value, preserving the nuclear:cytoplasmic ratio and fluid fraction. Note that this does not change the target values, so the cell will shrink or grow back towards its current target size. 
-
-+ Added 1-D diffusion solvers to BioFVM (useful for some coarse-grained problems). It solves for diffusion in the x-direction only. Use it by setting: 
-
-  microenvironment.diffusion_decay_solver = diffusion_decay_solver__constant_coefficients_LOD_1D
-  
-  Use this right after setup_microenvironment() in your main.cpp file. Future versions will include an XML option to use 1D. Most users will never need this. 
-  
-+ Added a standardized chemotaxis function to the standard models: 
-
-     void chemotaxis_direction( Cell* pCell , Phenotype& phenotype , double dt ); 
-
-  This sets:
-  
-     phenotype.motility.motility_bias_direction = direction * grad( index ), where 
-    
-     direction = phenotype.motility.chemotaxis_direction 
-        (1 to go up gradient, -1 to go down gradient)
-     index = phenotype.motility.chemotaxis_index 
-        (the index of one of hte diffusing substrates)
-
-+ Added Cell_Definitions in XML (beta feature) in response to SourceForge ticket 5. Users will be able to set the cell defaults definition by XML, as well as additional cell definitions that "inherit" phenotype parameters from cell defaults. This vastly reduces teh amount of necessary C++ to define a model. The new "template" sample project unifies 2D and 3D model specification using the new XML-based cell definitions. The next few releases will refine documentation and roll teh new XML-based cell definitions out to all the other sample projects. 
++ No major changes. See 1.7.0 for most recent major changes. 
 
 ### Minor new features and changes: 
 
-+ Created get_cell_definition(std::string) to return by reference the matching cell definition (search by name). Returns cell_defaults if nothing found. 
-
-+ Created get_cell_definition(int) to return by reference the matching cell definition (search by type). Returns cell_defaults if nothing found. 
-
-+ added int chemotaxis_index and chemotaxis_direction to the Motility class to assist with a new standard chemotaxis function. 
- 
-+ scale_all_secretion_by_factor also scales net_export_rates.
-
-+ sync_to_current_microenvironment and sync_to_microenvironment set up net_export_rates 
-
-+ Secretion::advance now updates net_export processes 
-
-+ Secretion::set_all_secretion_to_zero and Secretion::scale_all_secretion_by_factor act on net_export_rates as well. 
-
-+ Cell::turn_off_reactions acts on net_export_rates as well. 
-
-+ BioFVM::Basic_Agent::simulate_secretion_and_uptake now updates net_export processes, including impact on internal tracked substrate totals. (And all appropriate initializatoin functions have been updated. 
-
-+ Updated documentation to reflect the new net export rates. 
- 
-+ Updated the documentation to fully state the biotransport PDEs (for better clarity), including notes on the dimensions of the parameters. 
-
-+ Deprecated the following (unimplemented) function from the Volume class definition, as promised: 
-```
- void update( Cell* pCell, Phenotype& phenotype, double dt )
-```
++ Created new function std::vector<double> UniformOnUnitSphere( void ) that returns a (uniformly) random vector (x,y,z) on the unit sphere. 
 
-+ Added a new registry (unsorted map) of all cell definitions called cell_definitions_by_name and a vector of cell definitions called cell_definitions_by_index.  
++ Created new function std::vector<double> UniformOnUnitCircle( void ) that returns a (uniformly) random vector (x,y,0) on the unit circle (in the z = 0 plane).  
 
-+ The Cell_Definition default constructor and copy constructor automatically register all new cell definitions in cell_definitions_by_index; 
++ Created std::vector<double> LegacyRandomOnUnitSphere() that reproduces old behaviors of creating a random vector on the unit sphere. Never use this except if trying to replicate old results. Always use UniformOnUnitSphere() instead. 
 
-+ Created a display_cell_definitions(std::ostream&) function to quickly list all cell definitions and key information.  
++ Changed default placement of daughter cells to use UniformOnUnitCircle(), in response to longstanding "future plan" to "introduce improvements to placement of daughter cells after division."
 
-+ Created build_cell_definitions_maps() to create cell_definitions_by_name and cell_definitions_by_type. This should go at the end of create_cell_types(). 
++ All sample projects now check for <options> in their XML config files. 
 
-+ Created find_cell_definition(std::string) to return a pointer to the matching cell definition (search by name). Returns NULL if nothing found. 
++ Template projects calculate gradients and perform internal substrate tracking by default. 
 
-+ Created find_cell_definition(int) to return a pointer to the matching cell definition (search by type). Returns NULL if nothing found. 
++ Moved the bool is_active from "protected" to "public" in the Basic_Agent class in BioFVM_basic_agent.h, so that cells be be moved back into the domain and reactivated as needed. 
 
-+ Deprecated oxygen_index, glucose_index, TUMOR_TYPE, and VESSEL_TYPE from PhysiCell_Constants as promised. 
-
-+ Minor source code cleanup in PhysiCell_settings.cpp. 
-
-+ All sample projects now automatically build (and display) the registries of cell definitions via build_cell_definitions_maps() and display_cell_definitions(). 
-
-+ added the following std::vector<bool> to Microenvironment_Options to facilitate setting Dirichlet conditions on specific boundaries for specific substates: Dirichlet_all, Dirichlet_xmin, Dirichlet_xmax, Dirichlet_ymin, Dirichlet_ymax, Dirichlet_zmin, Dirichlet_zmax, Dirichlet_interior. 
-
-+ Minor cleanup in BioFVM_microenvironment.cpp 
-
-+ Microenvironment::update_dirichlet_node(voxel_index,substrate_index,value) now sets dirichlet_activation_vectors[voxel_index][substrate_index] = true; 
-
-+ Microenvironment::set_substrate_dirichlet_activation( int substrate_index , bool new_value ) now sets dirichlet_activation_vectors[voxel_index][substrate_index] for ALL Dirichlet nodes. 
-
-+ Microenvironment::apply_dirichlet_conditions() now checks the Dirichlet activation vector of the individual voxel. 
-
-+ Microenvironment::resize_voxels() and the various Microenvironment::resize_space() functions now resize dirichlet_activation_vectors, using the default dirichlet_activation_vector as the initial uniform activation vector. 
-
-+ Microenvironment::resize_densities() and the various Microenvironment::add_density() functions now resize dirichlet_activation_vector and use it to intialize dirichlet_activation_vectors at every voxel. 
-
-+ The various Microenvironment::add_density() functions now 
-
-+ Added function Microenvironment::set_substrate_dirichlet_activation( int index, std::vector<bool>& new_value ) to set the entire vector of activation at a specific voxel. 
++ Changed beta implementation of XML cell definitions: 
+  + In cycle, transition_rates renamed to phase_transition_rates. PhysiCell will give a deprecatoin warning for transition_rates until the official release of XML cell definitions. 
+  + In death, rates renamed to death_rates. PhysiCell will give a deprecatoin warning for transition_rates until the official release of XML cell definitions. 
+  + In cycle and death, "phase_durations" can now be used in place of phase_transition rates. This may be more intuitive for some modelers. 
 
++ See 1.7.0 for other recent minor changes.
 
 ### Beta features (not fully supported):
 
-+ Cell definitions can now be defined by XML files. See the note above. This functionality may be additionally refined in the next few releases while still in beta. 
-
++ Cell definitions can now be defined by XML files. See the note above. This functionality may be additionally refined or modified in the next few releases while still in beta. 
 
 ### Bugfixes: 
 
-+ In response to SourceForge ticket 25, added cell_defaults.phenotype.molecular.sync_to_microenvironment( &microenvironment ); to the create_cell_types() functions in the 2D and 3D template projects. 
-
-+ In response to SourceForge ticket 18, update_cell_and_death_parameters_O2_based() now checks for deterministic necrosis. 
-
-+ In response to GitHub issue 33, fixed issue where data-cleanup makefile rule gets a list of too many files. Rolled the new rule through to all the sample Makefiles as well. 
-
-```
-data-cleanup:
-	rm -f *.mat
-	rm -f *.xml
-	rm -f *.svg
-	rm -rf ./output
-	mkdir ./output
-	touch ./output/empty.txt
-```
-+ Updated Cell::Cell(), create_cell(), create_cell(Cell_Defintion), and convert_to_cell_definition() to call set_total_volume( phenotype.volume.total ). This makes sure that BioFVM knows the correct volume at the time of creation (or major update) so that it can save the correct values to outputs. This is in response to GitHub issue 22. 
-
-+ Removed the false statement from the user manual that stated that the cytoplasmic:nuclear ratio is between 0 and 1. 
++ In response to SourceForge ticket 26, fixed placement of parent cell in Cell::divide()
 
-+ Removed the false statement from the user manual that stated that relative cell rupture volume is between 0 and 1. 
++ Removed errant Cell_Definition in the new template sample project. 
 
-+ Updated the list of PhysiCell_Constants in response to SourceForge ticket 11. 
++ Added an extra check for bad chemotaxis definitions in response ot SourceForge ticket 28. 
 
-+ The various Microenvironment::add_density() functions now only set dirichlet_activation_vector = true for the newly added substrate, rather than *all* of them. This new vector is then used to initialize the activation vectors at every voxel. 
-
-+ Microenvironment::get_substrate_dirichlet_activation() mistakenly returned a double. Now it returns bool. 
++ Fixed bugs in processing of the "death" section of XML cell definitions.  
 
 ### Notices for intended changes that may affect backwards compatibility:
 
 + We intend to merge Custom_Variable and Custom_Vector_Variable in the very near future.  
 
 + We may change the role of operator() and operator[] in Custom_Variable to more closely mirror the functionality in Parameters<T>. 
 
-+ We will introduce improvements to placement of daughter cells after division. 
-
 + Some search functions (e.g., to find a substrate or a custom variable) will start to return -1 if no matches are found, rather than 0. 
 
 + We will change the timing of when entry_functions are executed within cycle models. Right now, they are evaluated immediately after the exit from the preceding phase (and prior to any cell division events), which means that only the parent cell executes it, rather htan both daughter cells. Instead, we'll add an internal Boolean for "just exited a phase", and use this to exucte the entry function at the next cycle call. This should make daughter cells independently execute the entry function. 
 
 + We might make "trigger_death" clear out all the cell's functions, or at least add an option to do this. 
 
 ### Planned future improvements: 
+
++ Methods or scripts to make "upgrading" PhysiCell easier for existing projects (to avoid overwriting the config file, Makefile, or custom files. 
 
++ Current "template" project will be rolled into a new "predator-prey" sample project, and "template" will be tidied up. 
+
 + Further XML-based simulation setup. 
+
++ current sample projects will be refactored to use XML cdell definitions. 
 
 + read saved simulation states (as MultiCellDS digital snapshots)
 

changes.md

@@ -2,11 +2,11 @@
 
 **Version:** 1.7.1
 
-**Release date:** ?? May 2020
+**Release date:** 2 June 2020
 
 ## Release summary: 
 
-This release ...   
+This release introduces bug fixes (particularly the placement of daughter cells after division), introduces new functions for uniformly random sampling of the unit circle and unit sphere, and refines the beta implementation of XML-based cell definitions. 
 
 **NOTE:** OSX users must now define PHYSICELL_CPP system variable. See the documentation.
 
@@ -22,35 +22,56 @@ This release ...
 
 + Created std::vector<double> LegacyRandomOnUnitSphere() that reproduces old behaviors of creating a random vector on the unit sphere. Never use this except if trying to replicate old results. Always use UniformOnUnitSphere() instead. 
 
++ Changed default placement of daughter cells to use UniformOnUnitCircle(), in response to longstanding "future plan" to "introduce improvements to placement of daughter cells after division."
+
++ All sample projects now check for <options> in their XML config files. 
+
++ Template projects calculate gradients and perform internal substrate tracking by default. 
+
++ Moved the bool is_active from "protected" to "public" in the Basic_Agent class in BioFVM_basic_agent.h, so that cells be be moved back into the domain and reactivated as needed. 
+
++ Changed beta implementation of XML cell definitions: 
+  + In cycle, transition_rates renamed to phase_transition_rates. PhysiCell will give a deprecatoin warning for transition_rates until the official release of XML cell definitions. 
+  + In death, rates renamed to death_rates. PhysiCell will give a deprecatoin warning for transition_rates until the official release of XML cell definitions. 
+  + In cycle and death, "phase_durations" can now be used in place of phase_transition rates. This may be more intuitive for some modelers. 
+
 + See 1.7.0 for other recent minor changes.
 
 ### Beta features (not fully supported):
 
-+ Cell definitions can now be defined by XML files. See the note above. This functionality may be additionally refined in the next few releases while still in beta. 
++ Cell definitions can now be defined by XML files. See the note above. This functionality may be additionally refined or modified in the next few releases while still in beta. 
 
 ### Bugfixes: 
 
 + In response to SourceForge ticket 26, fixed placement of parent cell in Cell::divide()
 
 + Removed errant Cell_Definition in the new template sample project. 
 
++ Added an extra check for bad chemotaxis definitions in response ot SourceForge ticket 28. 
+
++ Fixed bugs in processing of the "death" section of XML cell definitions.  
+
 ### Notices for intended changes that may affect backwards compatibility:
 
 + We intend to merge Custom_Variable and Custom_Vector_Variable in the very near future.  
 
 + We may change the role of operator() and operator[] in Custom_Variable to more closely mirror the functionality in Parameters<T>. 
 
-+ We will introduce improvements to placement of daughter cells after division. 
-
 + Some search functions (e.g., to find a substrate or a custom variable) will start to return -1 if no matches are found, rather than 0. 
 
 + We will change the timing of when entry_functions are executed within cycle models. Right now, they are evaluated immediately after the exit from the preceding phase (and prior to any cell division events), which means that only the parent cell executes it, rather htan both daughter cells. Instead, we'll add an internal Boolean for "just exited a phase", and use this to exucte the entry function at the next cycle call. This should make daughter cells independently execute the entry function. 
 
 + We might make "trigger_death" clear out all the cell's functions, or at least add an option to do this. 
 
 ### Planned future improvements: 
+
++ Methods or scripts to make "upgrading" PhysiCell easier for existing projects (to avoid overwriting the config file, Makefile, or custom files. 
 
++ Current "template" project will be rolled into a new "predator-prey" sample project, and "template" will be tidied up. 
+
 + Further XML-based simulation setup. 
+
++ current sample projects will be refactored to use XML cdell definitions. 
 
 + read saved simulation states (as MultiCellDS digital snapshots)