Warm States and Cold States

Delft-FEWS stores model states in the native model format.

Cold states: default initial conditions
- These are part of the Configuration (see Elementsoftheconfiguration).
- Stored in Config/ColdStateFiles/
Warm States: initial conditions from a previous run
- These are handled by Delft-FEWS
- Stored in zip files in the Delft-FEWS database with a time stamp and module instance reference, or
  Stored as a reference in the database, with the zip files in a WarmStateDirectory (see ClientConfig with warmStatesDirectory)

This page discusses the handling of warmStates.

State saving - <importStateActivity>

The <importStateActivity> is used to save a state.
This is configured at the end of the General Adapter module, see 05GeneralAdapterModule-importStateActivity.

By convention, only 'UpdateStates' (or Historical) Workflows save states at the end of the run.
Forecasts Workflows do not save their state typically.

<importStateActivity>
	<stateFile>
		<importFile>%WORK_DIR%/ToFews/outstates.nc</importFile>
		<!-- Rename imported state file so that it can be used as input state for a future model run. -->
		<relativeExportFile>../FromFews/instates.nc</relativeExportFile>
	</stateFile>
</importStateActivity>

State branches

Warm states written by the same ModuleInstanceId are part of a branch.
When a warmState on a branch expires, this breaks the branch and warmStates with a T0 before the expired state are no longer accessible as a warmState.

Example of states on a branch

Example based on the SLEIP application in Australia, which has separate workflows for:

annual Historical (AnnualUpdateState) model execution,
hourly Historical (HourlyUpdateState) model execution and
hourly Forecast model execution.

The AnnualUpdateState and HourlyUpdateState are identical,
except for their warmStateSearch period and T0.

The annual run
- looks for a warmState 24 years ago, and
- is run for T0 - 1 year.
The hourly run
- looks for a warmState between 1 and 2 years ago, and
- is run for T0 = currentSystemTime.
The Forecast run
- looks for a warmState at T0.

Even though both UpdateStates run the same GA, they need to get a different moduleInstanceId.
Otherwise, the annual warm state becomes invisible as soon as an hourly state expires.
This is because they exist on the same branch.

DELFT-FEWS Documentation > 02 State Handling by Delft-FEWS > image-2025-03-14-15-49-59-937.png

State selection - <exportStateActivity>

The <exportStateActivity> is used to start the model based on the initial conditions of a previous run (i.e. a warmState).
This is configured in the General Adapter module, see 05GeneralAdapterModule-exportStateActivity

The exportStateActivity can be used for any model Workflow (both UpdateStates and Forecasting)

<exportStateActivity>
	<moduleInstanceId>$Catchment$WflowHc</moduleInstanceId>
	<stateExportDir>%WORK_DIR%/FromFews</stateExportDir>
	<stateSelection>
		<warmState>
			<stateSearchPeriod unit="hour" start="-240" end="-5"/>
		</warmState>
	</stateSelection>
</exportStateActivity>

stateSearchPeriod

The <stateSelection> defines which state is exported to the model and so determines the start of the simulation, see 05GeneralAdapterModule-stateSelection
Typically, a <warmState> is configured in the search period. If no warmState is found, the default coldStateFile will be used at the beginning of <stateSearchPeriod>.

The stateSelection search period can be set in several places.
The hierarchy follows the order shown below, i.e. Topology overrules ModuleConfigFile etc.
In case of nested Workflows, the top-level Workflow overrules the underlying nested Workflows.

Topology (see 24Topology-Warmstateselection),
General Adapter moduleConfigFile (see 05GeneralAdapterModule-stateSelection),
WorkflowDescriptors, see <stateSelection> in 13 WorkflowDescriptors), or
TaskRunProperties in the Admin Interface (LINK NEEDED)

Time for which a warmState is created

Default behaviour: Warm state is written at the end of the simulation
- This is determined by the end of the forecast length
- For UpdateStates (Historical) Worflows this is typically T0

There are two options in <exportStateActivity> to also save warmStates at other times.

<loopTimestep>, see 05GeneralAdapterModule-loopTimeStep
- All activities are run in a loop to ensure a state is written on every cardinal time step between the exported state time and T0.
- This has two advantages:
  - States are equally and frequently distributed over time, so it is possible to start an UpdateStates workflow from every point.
  - Reduces memory consumption, one can run a simulation over months without going out of RAM.
<writeIntermediateState>, see 05GeneralAdapterModule-writeIntermediateState
- An extra state is written at the end of the state search period.
- Note that this will split the run in two. For example, if <stateSearchPeriod> is -10 to -4 days, then there are two update runs:
  - one from the time where a state was found to -4 days and
  - one from -4 to T0
  - A state is written at the end of both runs (T0 - 4days and T0).
- (Optional) <minimumRunLength>, see 05GeneralAdapterModule-minimumRunLength.
  - Splits the run in two only if both runs can be run over the minimum run length.
  - If not, there is only one run and the state is written to the end of this run (T0), no intermediate state is written.

Reduce number of warmStates in the database

In some cases, transient States can be usefull, see 02Statehandling-TransientandLongLivingStates (below).

There are two options in <exportStateActivity> to reduce the number of warm states in the database:

<searchForTransientStates>, see 05GeneralAdapterModule-stateSelection
- True (default): prefered value for Forecasts workflows
- False: can be used for UpdateState workflows to exclude warmStates that are created after the stateSearchPeriod
  - Prevents transient states to become part of the long living state branch.
  - Use in combination with <transientStateExpiryTime> to set a shorter expiryTime, see below.
<transientStateExpiryTime>
- Use in combination with <searchForTransientStates>, see above.
- In the state selection you can configure the transient state expiry time, for example 1 day, and the task run expiry time.
- For the long living states the expiry time of the state run is used.
- Remember states cannot live longer than the update run that creates them.

Transient and Long Living States

Example based on the the CHPS application in the USA, which has separate workflows for:

Historical (UpdateState) model execution,
Forecast model execution and
Ensemble Forecast model execution.

The state handling of these is described in more detail in the table below.

State creation within and after stateSearchPeriod

The UpdateStates run produces 10-15 warmStates every time it's run (i.e. daily).
Typically, only those at the end of a stateSearchPeriod are used:

T0-10d for Forecasts,
T0 for the Ensembles
T0-9d for UpdateStates (the next day)

All warmStates outside its own stateSearchPeriod will be superseded by next day's run.
But all remain in the database until they expire, which is when the workflow expires.

States created after the stateSearchPeriod of the GA that creates them are considered transient states.
States created within the stateSearchPeriod of the GA that creates them are considered long living states.

UpdateStates workflow in CHPS The run starts at the end of the warm state search period, at the blue solid square. UpdateState workflows cannot be run from the Topology. Instead, they are scheduled to run on server once a day (midnight, 12z), with: T0: 12z <stateSearchPeriod> for warmStates: T0 -15 days till T0 -10 days start of run: To - 10 days (typically) end of run: T0 <loopTimeStep>: 12z, so generate a state every day <simulatedHistoricalModuleInstanceId>: to link to the Forecasts
Forecasts workflow in CHPS The run starts at the end of the warm state search period, or just at T0-10days if this is configured as such in the Topology.xml Forecast workflows can be run from the Topology, with: T0: a cardinal time step <stateSearchPeriod> for warmStates: T0 -15days till T0-10 days start of run: T0 - 10 days (typically) end of run: forecast length do not generate states Modifiers for the Forecasts (<T0) are applied to UpdateStates.
Ensembles worflow in CHPS Similar to Forecasts workflows. Ensemble workflows can be run from the Topology, with: T0: a cardinal time step <stateSearchPeriod> for warmStates: T0-10 till T0 days start of run: T0 (typically) end of run: forecast length do not generate states Modifiers for the Forecasts can be excluded from the Ensembles.
UpdateStates workflow with Transient states With `<searchForTransientStates>` = False, only long living states are used. Consequently, the UpdateState run will start one day earlier (T0-11days). After all, the state at T0 is a transient state produced by the UpdateState run of T0-1d.

<workflowDescriptor id="UpdateStates" forecast="true" visible="true" allowApprove="true"   autoApprove="true"> 
	<description>UpdateStates</description> 
	<cardinalTimeStep id="12Z"/> 
	<stateSelection> 
    	<warmState> 
        	<stateSearchPeriod start="-15" end="-10" unit="day"/> 
            <searchForTransientStates>false</searchForTransientStates> 
            <transientStateExpiryTime multiplier="1" unit="day"/> 
    	</warmState> 
	</stateSelection> 
	<runExpiryTime multiplier="30" unit="day"/> 
</workflowDescriptor>