PhaseContainer
Miscellaneous functions PhaseContainer
syntax
- PhaseContainer(container, string message)
description
PhaseContainer calculates all Subitems in the specified Container that are made available to consumers as subitems of the resulting container and posts the configured string message in the EventLog when finished before any of the resulting subitems can be used. This forces the scheduler to first complete a set of calculations before commencing on a subsequent set.
Any calculation task that is scheduled after the calculation of a fenced container only starts when all fenced tasks are completed. This enables a modeller to synchronize memory-intensive sub-tasks and to limit the simultaneous memory allocation of such separated sub-tasks.
Note that this operator is especially effective when using it to denote a ‘calculation block’ of which all preparatory steps can be removed from memory when finished calculating. Then, only the result (in the PhaseContainer) is kept in memory and ready for use in the next step in the model.
If the message is all that is wanted and the serialisation is not, use CalcAndWrite instead: it posts the same kind of message when an item has finished calculating, without fencing anything.
a phase only runs when something reaches it
A PhaseContainer is not executed because it exists; it is executed because something asks for it. There are three ways to reach one:
- an item outside the phase uses the data of one of its members, for example
phase/resultin a calculation rule, - a member of the phase is updated, for example by naming it in ExplicitSuppliers, or
- the phase container itself is updated, for example by naming it in ExplicitSuppliers or by requesting it on the GeoDmsRun command line.
The second way is the common way to sequence exports, which does not use the data of anything:
parameter<string> Generate := 'Ready', ExplicitSuppliers = "WriteResults";
container Results := PhaseContainer(GetResults, 'Results for ' + Tile_name);
// elsewhere, the driver that pulls the tiles:
parameter<string> Step := 'Ready', ExplicitSuppliers = "PerTile/tile_0/Results/Generate";
Here nothing ever asks for the value of Results/Generate; the string 'Ready' only exists to carry the supplier relation, and that is enough to run the phase, with its fence and its PhaseContainer(...) message.
what a phase calculates
A phase calculates the members that are demanded, and leaves the rest of the fenced container alone. A fence over a container of three results of which only one is consumed calculates that one, as the same container without the fence does, so a fence placed to bound the working set does not widen it. A member that is demanded but has neither a calculation rule nor a storage to read it from is nothing for the phase to collect; the phase then reports
PhaseContainer: Source <item> has no calculation rule so its data cannot be collected
for that member.
The units of a fenced container are still supplied as a whole, because a consumer that names phase/u as its domain resolves through the mirror unit. Only the values are on demand.
what the message means
The PhaseContainer(<n>): <message> line reports that the phase has completed: the work behind the fence that this phase collected has finished and its results have been handed to the phase’s members. It is therefore usable as per-tile progress reporting in a tiled batch model.
The message appears when the phase completes, not when a consumer pulls its result. That also holds for several independent phases gathered by one expression, for example
parameter<string> Generate := ='add(' + asList('PerTile/' + Tiles/name + '/Results/Generate', ',') + ')';
where each tile reports when its own work is done, not all of them at the end. A phase needs no eager consumer for this, so tiles that are otherwise independent need not be coupled, for instance by letting tile k+1 name the phase result of tile k in its ExplicitSuppliers; such a coupling makes invalidating tile k invalidate every later tile.
phase results cannot be used in indirect expressions
An indirect expression may not use an item whose calculation requires a PhaseContainer. That holds for indirect calculation rules and for indirect properties, most commonly an indirect StorageName such as
unit<uint32> WriteResults : nrofrows = 1
, StorageName = "='%LocalDataDir%/out/' + Start/Tile_name + '.dbf'";
GeoDMS reports the item carrying the indirect expression and the phase result it requires.
Indirect expressions are resolved inline while the item’s calculation rule or metadata is being determined. Entering a PhaseContainer from there cannot preserve the fence’s scheduling guarantee.
Make the indirect expression depend only on pre-fence values. It may still produce an expression that names a phase result; only using a phase result to calculate the expression text is forbidden. For example, choose the member name from pre-fence data and return Start/result, instead of reading Start/selector while constructing that name. ExplicitSuppliers is not a workaround for this error.
since version
The fence for the tasks scheduled after a phase since 14.4.0.
example
container Results := PhaseContainer(Results0, 'Results for '+Context/ThisIterName+' are finished calculating');