Documentation warning about aliased references

[artgoldberg]

Because obj tables Model instances are indexed by unique keys, unexpected behavior can arise from aliased references. E.g., suppose that a person using wc_lang creates two reactions Models that use the same flux_bounds (another Model) in a whole-cell model model. Let the reaction ids be 'ex_m1' & 'ex_m2'. Then these expressions refer to the two reactions

model.reactions.get_one(id='ex_m1')
model.reactions.get_one(id='ex_m2')

And these expressions refer to the FluxBounds Model that they share.

model.reactions.get_one(id='ex_m1').flux_bounds
model.reactions.get_one(id='ex_m2').flux_bounds

Thus, any changes to one flux_bounds entity will change the other. These two references to one FluxBounds Model are called 'aliases' in Computer Science, which has studied aliasing deeply, especially in computer language and compiler theory (google scholar "mark wegman aliasing").

Aliasing is likely to cause problems for obj model users that don't expect aliasing, i.e., that don't realize that multiple references point to the instance. E.g., model.reactions.get_one(id='ex_m1').flux_bounds.min *= 10 would also change the value of model.reactions.get_one(id='ex_m2').flux_bounds.min which might not be expected.

The only possible technical change obj tables could make to address this would be to avoid reusing objects just on the basis of data values in unique keys. However, that would likely have other consequence.

Other than that, there's nothing technical obj tables can do to address this. Warnings aren't appropriate, and would almost certainly be ignored; and errors aren't appropriate. So the best thing to do is alert users to this issue in the obj tables documentation.