Field access checks

[llaniewski]

This PR introduces a new mechanism for setting and testing the access policy for fields in stages.

Setting access

The AddStage has now three arguments:

• load.densities= specifies the Densities that are loaded at the beginning of the stage.
• read.fields= specifies the Fields that can be accessed in the Dynamics with field(dx,dy,dz) macros.
• save.fields= specifies the Fields that are saved at the end of the stage.

Defaults

By default the actions/stages setup is:

AddStage(main="Run", name="BaseIteration", load.densities=TRUE, read.fields=TRUE, save.fields=TRUE)
AddStage(main="Init", name="BaseInit", load.densities=FALSE, read.fields=FALSE, save.fields=TRUE)
AddAction(name="Iteration", stages=c("BaseIteration"))
AddAction(name="Init", stages=c("BaseInit"))

Moreover, the default read.fields is as allowing as possible. If not specified otherwise it is assumed that stage has read access to all fields that are available to it.

Checks

The access policies are checked in each Action (series of Stages) assuming:

• You cannot read a field which wasn't written.
• You cannot overwrite already written fields
• You should write all fields by the end of the action
• Init action should not read anything from previous iteration.

Exceptions

There are three mechanisms to circumvent checks:

• non.mandatory=TRUE in AddField signals that this field doesn't have to be written by the end of an action
• can.overwrite=TRUE in AddStage signals that a stage can overwrite fields
• SetOptions(permissive.access=TRUE) switches the test entirely and sets all fields to be readable in all stages. This should be avoided

Modifications

Some adjustments were made to models to agree with these policies. All models were tested and permissive.access=TRUE was added to the ones failing from this change. These models should be fixed to accommodate these checks. Especially d3q27_pf_velocity, as per #437.

[codecov-commenter]

Codecov Report

Patch coverage has no change and project coverage change: -0.02% ⚠️

Comparison is base (07dd2b9) 44.10% compared to head (55c4849) 44.08%.

❗ Your organization is not using the GitHub App Integration. As a result you may experience degraded service beginning May 15th. Please install the Github App Integration for your organization. Read more.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #444      +/-   ##
===========================================
- Coverage    44.10%   44.08%   -0.02%     
===========================================
  Files          166      166              
  Lines         7818     7821       +3     
===========================================
  Hits          3448     3448              
- Misses        4370     4373       +3     

Flag	Coverage Δ
d2q9	30.54% <0.00%> (-0.01%)	⬇️
d2q9_bc	26.81% <0.00%> (-0.01%)	⬇️
d2q9_kuper	27.51% <0.00%> (-0.01%)	⬇️
d3q27_PSM_NEBB	35.71% <0.00%> (-0.02%)	⬇️
d3q27_pf_velocity	30.45% <0.00%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed	Coverage Δ
src/LatticeAccess.inc.cpp.Rt	96.42% <ø> (ø)
src/cuda.cu.Rt	92.59% <0.00%> (-7.41%)	⬇️

... and 1 file with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[llaniewski]

I added feature for plotting the stages and their access to a pdf file. The plot shows the field read and write status and marks problems in red. When you run

make d3q27_pf_velocity/summary

this nice plot is generated:

FYI: @TravisMitchell @shkodm @mdzik