expose and parse the mechanics grid size in XML

[rheiland]

The mechanics voxel size has had a default of 30 and has been hard-coded in main.cpp since PhysiCell came out. This PR makes it possible to easily modify that value in the XML config file. A new tag <mechanics_voxel_size> now exists in the <options> block. And PhysiCell_settings.mechanics_voxel_size now exists and =30.

For all sample projects (and the ode intracellular project):

• inserted <mechanics_voxel_size>30</mechanics_voxel_size> into the config files
• modified main.cpp to no longer hard-code 30; rather, read it from PhysiCell_settings.mechanics_voxel_size

Added unit_tests/mech_voxel_size/ which contains a directory structure and files suitable for /user_projects:

• includes three /config files for different sized mechanics voxel sizes: test_mech_grid_size_{20,25,30}.xml
• the domain size [-300,300] was chosen to be the least common multiple of those 3 sizes (and the domain grid has the typical dx=dy=dz=20)
• the main.cpp of this unit test has commented out microenvironment.simulate_diffusion_decay, primarily to see if it would affect the following issue (it didn't).

We may want to discuss some (perhaps) surprising results from just changing the mechanics voxel size, as the above unit test should demonstrate: we end up with a different number of agents. Aside from this, even if the number of agents had been the same, we may end up with different cell scalars, e.g., pressure, if those scalars depend on the neighbor cells which depends on the Moore neighborhood which depends on the mechanics voxel size.

A better explanation of why changing the mechanics voxel size may lead to different simulation results is now found in the README.md of the unit test.

[drbergman]

Love that this exposes this part of the model! Looks like a straightforward implementation of it, which will make it easy for users to pick up. I like the decision to have the stdout print if it's not in the XML as a way to inform users about this change. I also like that this message will only be read by those who look carefully through the initial model logs, since it is something that can be dangerous (see the comment Randy opened this PR with).

I raised two points here for discussion / to address. First, this PR has mechanics_voxel_size defined both in PhysiCell_constants and in PhysiCell_settings. My vote is for having it within PhysiCell_settings, and that is where the XML parser puts it now.

Second, I think we should completely remove mechanics_voxel_size from the main.cpp files. We should use the new PhysiCell_settings.mechanics_voxel_size within the called create_cell_container_for_microenvironment.

Looking forward to discussing and eventually merging! I heard that changes to Studio are already in dev (not sure branch or not), but happy to help any way I can there.

[asmelko]

Good work of pointing out this issue!

I think this is a step in the right direction. The thing with mechanics voxel size is that when its too low, some real neighbors may not be present in the moore neighborhood; when its too high, we are spending extra work on computing distances between cells that will never become neighbors.

So if our code automatically modifies the voxel size according to the max interaction distance in each mechanics step, we will arrive at the optimal solution.

[drbergman]

The cost there, @asmelko, is recreating the agent grid each step. If we could rebuild this for cheap, then that is a good idea.

@asmelko Do you know a way to adjust the agent grid for cheap? We know it will be similar to the grid at the previous step, but I don't know how we use that to reconstruct it for cheap on changing the grid size.

[drbergman]

Is there a reason we need to reference the mechanics voxel size in main.cpp? Can't we have create_cell_container_for_microenvironment just read the voxel size in the PhysiCell_settings object?