simplified dc functions

[drbergman]

The current API for the Dirichlet nodes is inconsistent and confusing (See #214). To simplify the API for users, I have created two functions that handle all the DC logic in a straightforward, intuitive, and consistent manner. Several variants are included for those looking to fully optimize these calls (though unless the model is changing DC activations nearly every diffusion_dt, I doubt they matter enough to be noticed). The old API, using verbs add, update, and remove remain so that we can preserve backwards compatibility. The new API uses fix and unfix.

New API

To fix a substrate at a voxel, i.e., set a DC condition, users can call

fix_substrate_at_voxel(std::string substrate_name, int voxel_index[, double new_value]);

where new_value is optional¹.

To unfix a substrate at a voxel:

unfix_substrate_at_voxel(std::string substrate_name, int voxel_index);

In these and all cases that follow, passing in int substrate_index in place of substrate_name is allowed.

Handling Boolean activations

The confusing part of the previous API was the inconsistency of updating the Booleans that tracked which (voxel, substrate), voxel, and substrate had active DCs. This new proposed API handles these consistently:

• dirichlet_activation_vectors maintains the lowest level detail where dirichlet_activation_vectors[voxel_index][substrate_index] indicates whether that substrate is has a DC at that voxel
• dirichlet_activation_vector maintains whether a substrate has a DC anywher and is accessed by dirichlet_activation_vector[substrate_index]
• voxel.is_Dirichlet maintains whether any substrate has a DC at the given voxel

Convenience API to (possibly) save time

Maintaining the above Boolean activation values can incur unnecessary computational expense if fix-ing or unfix-ing many substrates/voxels at once. For users who wish to save even these scraps of time, the following are implemented to update the Boolean variables after accounting for all the changes:

fix_substrate_at_voxels(std::string substrate, std::vector<int>& voxel_indices, std::vector<double>& new_values);
unfix_substrate_at_voxels(std::string substrate, std::vector<int>& voxel_indices);

Fix with flexible value update

Anticipating users turning "back on" a DC, the fix_... calls do not require passing in a value. In this case, whatever value was in dirichlet_value_vectors[voxel_index][substrate_index] remains.

fix_substrate_at_voxel( std::string substrate, int voxel_index );
fix_substrate_at_voxels( std::string substrate, std::vector<int>& voxel_indices );

Similarly, if fix multiple voxels at once with uniform DCs, just the one value can be passed:

fix_substrate_at_voxels( std::string substrate, std::vector<int>& voxel_indices, double new_value );

All substrates in a voxel at once

To support changing all substrates in a voxel at once, the following three functions are provided:

fix_substrates_at_voxel( int voxel_ind, std::vector<double>& new_values );
fix_substrates_at_voxel( int voxel_ind );
unfix_substrates_at_voxel( int voxel_index );

Footnotes

1. It does not use an optional arg, but just has two implementations ↩

[Copilot]

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

BioFVM/BioFVM_microenvironment.h:244

• Consider renaming the parameter 'voxel_ind' to 'voxel_index' for consistency with the rest of the API.

void fix_substrates_at_voxel( int voxel_ind, std::vector<double>& new_values );