FFTools Plug-In: Scheduled Element State Module (SES)

Main FFTools Page | Description | Approach | Setup | Input File Format | Example | SES Output Log

Description

The Scheduled Element State (SES) module allows modelers to automate, or schedule, transient changes in an element's state of activity. This has proved to be a useful feature with projects that contain large structures that change gradually through time, for example:

• Mine pits,
• Tunnels,
• Earthen dams, or
• Tailings impoundments

Because these structures can take years to construct or excavate, often the changing size and shape of the structure has an effect on the flow system, and using traditional methods, these changes are very difficult to model.

To model these structures traditionally, all the elements in the model would have to be active for the full model run, or the model would have to be run in phases where features would be added or removed, before resuming the model. Having active elements represent something that does not yet exist, or stopping a model, adding a feature, and resuming the model often creates numerical stability problems and forces the modeler to compromise aspects of the conceptualization.

SES allows for small, transient adjustments to the model. These can match the actual or planned physical changes in the field. While these changes can affect model stability, using small time steps, and making only small changes during any single time step, improves stability.

SES allows for elements to be activated or inactivated during a model run, and it monitors associated water-budget changes (FEFLOW does not currently monitor lost or added water associated with changes in element activity). When structures are large (composed of many elements), leaving the elements inactive when not in use can save significant computer processing time.

SES is designed to work with other FFTools modules. The FEFLOW plug-in (IFM) architecture is very flexible, but it does not allow independent plug-ins to check what other plug-ins are doing. This can cause issues where the behavior of one plug-in modifies a model feature another plug-in has also modified. SES is designed to work with other modules: SHB (Scheduled Head Boundary), BUDGET and LAKE3D.

Note: This module does NOT correct head, pressure or saturation for deformations in the materials that might be caused by deposition or excavation. This module also does not account for effects related to solute transport, density and viscosity variations, or thermal energy.

Suggested FEFLOW Configuration

The SES module has been tested on models with the following characteristics:

• FEFLOW version 7.x
• Three-dimensional mesh using layered prismatic elements (prismatic elements having a triangular shape in horizontal cross section)
• All slices set to "fixed" in FEFLOW's "3D Layer Configuration..." editor
• FEFLOW Problem Class: Richard's equation for variably-saturated media
• State: Transient

Approach

Model element maybe activated or inactivated following a linear schedule.

Inactivating Elements

Element inactivation is more straightforward than activation. For example, a modeler can use inactivation to simulate mine-pit excavation. As material is mined, the wet material represented by an element is removed, and all or some of the faces of the now air-filled element may be seepage faces (handled by SHB). If recharge over the excavation is simulated, FEFLOW will apply it to the top-most active element. SES also tracks and records any residual water removed with the element when it is inactivated.

Note: if the bottom of an element is below the ultimate elevation of an excavation, the element will NOT be inactivated.

Activating Elements

Activating elements requires more user specifications than does inactivation. When an element is activated, assumptions must be applied regarding its saturation:

• Is it a partially saturated element?
• Is it a fully saturated element?

When using Richard's Equation, active elements cannot be completely dry. For example, assume that a 1,000 cubic-foot element with 20% porosity and a residual (minimum) saturation of 5% is activated. If the modeler specifies that the element is activated with a saturation equal to its residual saturation, the added water volume would be 10 cubic feet. However, if the element is activated with full saturation, the added water volume would 200 cubic feet, 20 times more water.

In most cases of element activation, one or more of the nodes located at the corners of the element will not be active. At these nodes, which will become active at the time the element is activated, the saturation at the nodes must be supplied as input by the user. The nodal saturation is, in turn, specified by an initial water level at such nodes. By default, FEFLOW uses the water levels that the user specifies for initial water levels at the beginning of the simulation. FEFLOW's default initial-condition water level may or may not conform to the user's conceptualization of the problem. For this reason, SES allows the user to over-ride FEFLOW's default values by using various SES options to directly or indirectly set the water level at newly activated nodes (also sets the initial volume of water in the newly activated element).

Scheduling the Active State of Elements

Elements within an SES group are activated or inactivated on a user-defined schedule based on the elevation of a user-defined point in each element (top, middle or bottom). For each group of elements on which SES will operate, the user defines a linear rate of activation/inactivation which is computed from the user inputs of start and end times, and start and end elevations. Each rate the user defines using these inputs defines an SES "stress period". The user can define multiple stress periods for each SES group, but, to avoid simulation errors, there must not be any timing overlaps or gaps in the stress periods for a group.

The user-specified rate is used to compute an "SES elevation" for the corresponding SES group of elements at the time midway between the start and end of the current FEFLOW time step. Activation of an element occurs when the SES elevation first exceeds the elevation of the user-defined trigger elevation within the element. Similarly, inactivation occurs when the SES elevation first falls below the elevation of the user-defined trigger point within the element. The equation used to compute the current SES elevation of group "g" during that group's i-th time period is:

Current_SES_Elevation_g,i = E_g,s,i - (((T_mTS - T_g,s,i) / dT_g,i) * dE_g,i)

E_g,s,i is the start (s) elevation of SES group "g" during the SES group's i-th time period (specified input: StartElev(i))
T_mTS is the time midway (m) between the beginning and end of the current FEFLOW time step (TS)
T_g,s,i is the start time of SES group "g" during the SES group's i-th time period (specified input: StartTime(i))
dT_g,i is the difference between the end and start times of SES group "g" during the SES group's i-th time period (computed from specified inputs, EndTime(i) - StartTime(i))
dE_g,i is the difference between the start and end elevations of SES group "g" (computed from specified inputs, StartElev(i) - EndElev(i)))

Note that for a rising SES elevation, dE is negative because the start elevation is below the end elevation.

Note: The state of an SES-controlled element will be changed if any portion of an SES schedule overlaps with the current FEFLOW time step. If FEFLOW's automatic time stepping is used, SES creates a new FEFLOW power function (time-series) named "SES:reserved". This new power function will alter FEFLOW's automatic time stepping so that its time steps coincide with SES-scheduled start and end times. In FEFLOW's problem-settings menu, if the user specifies either "constant time steps" or "varying time steps", the modeler is responsible for ensuring that time steps align with SES specifications. If the user does not manage the scheduling, then element states may change either too soon or too late after the end of a specified end time.

For example, for constant excavation through ten 100-foot thick, horizontally oriented model layers over ten years, the rate of inactivation would be one layer of elements per year.

If multiple rates are needed for different portions on the model, multiple SES element groups can be defined, each with its own trigger specifications.

Setup

Activation and input for SES is specified via the SES tab of the FFTools Plug-in edit window. Input is read from a structured ASCII file and can be stored in the FEM. If stored in the FEM, the module will always read the data in the FEM instead of from the structured file unless the user specifically requests input via a structured file. The current configuration stored in the FEM file can be exported to a structured file, as well as current SES element groups; this information can then be edited and re-imported. Logging of SES-specific simulation results can be specified.

Format of the SES Setup File

At least one complete group of elements must be specified. The input instructions below display a comma followed by a space between each input value. The commas are required, but the spaces are optional. Keywords or characters are shown in italic font.

The first line must be:

• Input L1

  SES

After the first line, a set of SES element groups is listed. Within a "GROUP set," one or more SES groups is listed sequentially. After the first GROUP set, a second GROUP set can be listed, followed by a third, a fourth, etc., until all such sets are listed. The number of GROUP sets is not limited. This approach allows the user to manage GROUP sets separately in a complex transient model. For example, in a model that simulates both excavation of a mine and filling of a tailings storage facility, one GROUP set could be used to specify the excavation of the mine and a second GROUP set could be used to specify infilling of the TSF.

The first line of any GROUP set must be:

• Input L2

  GROUP

• Under L2, an unlimited number of individual SES element groups can be listed. Repeat L2A, L2B, and L2C for each group.
  • The format of the next input, L2A, specifies whether the individual group will be activated or inactivated:
    • Input L2A, Elements will be ACTIVATED:

      #GroupID, TriggerOption, FlipState, ChangeRCHOnActivate, RCHRate, HeadSetRule, NodeRulePct

      Note: FlipState MUST equal 1 (one).

      Note: NodeRulePct can be omitted for any HeadSetRule that does not use it.

    • Input L2A, Elements will be INACTIVATED:

      #GroupID, TriggerOption, FlipState, DisableRCHOnInactivate

      Note: FlipState MUST equal 0 (zero).

  • The next input, L2B, defines the elements included in an individual group. Only one option can be used for a specific individual group, but a mix of options can used in a GROUP set. For example, group #12 can use the L2B "XML" option, and group #7 can use the "S" option. L2B format options are:
    • Input L2B (option 1): List the FEFLOW number of every element in the group:

      E, ElemNo(1), ElemNo(2), ElemNo(3), ... ElemNo(n)

    • Input L2B (option 2): List the FEFLOW number of every Layer 1 element in the group, then on the next line list the number of layers to manage under each top element including the top layer. The number of entries of elements and layers must the same:

      S, ElemNo(1), ElemNo(2), ElemNo(3), ... ElemNo(n)

      Layers(1), Layers(2), Layers(3), ... Layers(n)

    • Input L2B (option 3): List upper-most and bottom-most elements in the group. SES will assume all elements between the tops and bottoms are part of the group. If the top and bottom element are on the same layer, only one entry is needed (note that accidental omission of an element number will result in SES assuming that fewer than intended elements belong to the group). Elements can be listed in any order:

      V, TopElemNo(1), TopElemNo(2), TopElemNo(3), ... TopElemNo(n), BottomElemNo(1), BottomElemNo(2), BottomElemNo(3), ... BottomElemNo(m)

    • Input L2B (option 4): A FEFLOW XML element-selection file can be used to define all the elements in the group. This method allows the user to use FEFLOW tools to create and view the elements in the group.

      XML, XMLFilename

  • Input L2C lists the SES elevation and timing from which the linear rates of activation or deactivation are computed for an individual group. Use as many records as needed to define the changing rates over time. For example, group #10 defines 5 phases of excavation. For group #10, five L2C lines must be listed. Note that gaps in the timing or elevation between rates are not allowed (if such gaps are needed, use two or more groups to define the gaps). For example, StartTime(2) MUST equal EndTime(1), StartTime(3) MUST equal EndTime(2), etc., and the same is true for StartElev(i) and EndElev(i) entries. The format of L2C is:

    StartTime(1), EndTime(1), StartElev(1), EndElev(1)

    StartTime(2), EndTime(2), StartElev(2), EndElev(2)

    ...

    StartTime(i), EndTime(i), StartElev(i), EndElev(i)

    ...

    StartTime(n), EndTime(n), StartElev(n), EndElev(n)

    Note that if an element's StartTime(i)falls after T_mTS but before the end of the time step, SES will not flip the state of the element until the next time step.

Regardless of which element input method is used (E, S, V, XML) every element on which the user want SES to act must be defined. The GROUP formats E, S, or V offer more flexibility in defining the elements, but by using the XML format, the FEFLOW GUI can be used to define the elements which simplifies setup of the SES input file.

The variable definitions are:

• GroupID: Identifier for the current SES element group. The identifier is a positive integer value preceded by a "#" (for example, to specify a GroupID of five, the first entry of L2A should be "#5")
• TriggerOption: An integer that specifies the trigger elevation in or on the element for flipping the element's state of activity. The following options are currently available:
  1. Use the node on the element with the lowest elevation
  2. Use the average elevation of nodes defining the bottom triangular face of the element
  3. Use the average elevation of the 6 nodes defining the faces of the element
  4. Use the average elevation of nodes defining the top triangular face of the element
  5. Use the node on the element with the highest elevation
• FlipState: An integer that specifies whether elements will be switched on or off. Note that if the same set of elements are to be activated and inactivated at different times, two GROUP sets must be defined. A GROUP of elements can only follow an activation schedule, or an inactivation schedule.

  0 = elements inactivated (all elements in the group are assumed to be initially active)

  1 = elements activated (all elements in the group are assumed to be initially inactive)

• ChangeRCHOnActivate: An integer that specifies how recharge is handled upon flipping the element's state:

  If FlipState is 0:

  0 = Surface recharge is not changed by the inactivation of elements (FEFLOW's method of transferring recharge to the top-most active element is implemented without any change)

  1 = Surface recharge set to zero at same time element is inactivated (NOTE: transient recharge may not be recorded in the DAC file).

  If FlipState is 1:

  0 = Surface recharge not changed by the activation of the element (FEFLOW's method of transferring recharge to top-most active element is implemented without any change)

  1 = Surface recharge will be set to "RCHRate" noted next.

• RCHRate: A real number specifies the new rate of recharge for a newly activated element (NOTE: this is intended for cases in which the newly activated element is the highest active element).
• HeadSetRule: An integer that specifies how to set the initial nodal water level at a newly activated node. Ignored if FlipState is 0 (inactivation). The following options are currently available:

  "0" : Set the water level to the average of the water levels of nodes that are in contact with neighboring active elements

  "1" : Set the water level to the elevation of the newly activated node

  "2" : Set the water level to the water level of the node directly below the newly activated node

  "3" : Set the water level to an elevation somewhere between the elevation of the newly activated node and the elevation of the node directly below the newly activated node. The vertical distance between the two nodes is multiplied by NodeRulePct and added to the elevation of the node below the newly activated node. The water level of the newly activated node is then set to this result.

  "4" : Set the water level to an elevation somewhere between the FEFLOW-default water level of the newly activated node and the water level at the node directly below the newly activated node. The difference between the two water levels is multiplied by NodeRulePct and added to the water level at the node below the newly activated node. The water level of the newly activated node is then set to this result.

  "5" : Set the water level at the newly activated node to the average elevation of the 6 nodes defining the newly activated element

  "6" : Set the water level to an elevation somewhere between the average elevation of the bottom of the newly activated element and the average elevation of the top of the newly activated element. The vertical distance between these two averages is multiplied by NodeRulePct and added to the average elevation of the bottom of the newly activated element. The water level of the newly activated node is then set to this result.

• NodeRulePct: A real number between 0 (zero) and 1 (one) used for HeadSetRule options 4, 5, and 7.
• SES time and elevation intervals (for the current SES group, an unlimited number of SES time and elevation intervals are allowed):
  • StartTime(i): A real number that specifies when to begin the process of flipping the state of elements for the i-th time period of the current group.
  • EndTime(i): A real number that specifies when to stop the process of flipping the state of elements for the i-th time period of the current group of the current group.
  • StartElev(i): A real number that specifies the elevation at which state flipping will begin for the i-th time period of the current group.
  • EndElev(i): A real number that specifies the elevation at which state flipping will stop for the i-th time period of the current group.
    See "Scheduling the Active State of Elements" regarding the calculation of the current SES elevation.

Example

Using SES is shown in two example models. One is a small model focused on SES. The other is a larger model combining all the FFTools modules (CRB, LAKE3D, OBS, SES, SES, SHB, and BUDGET). The small model is discussed here only to show the input file format. The details on the model are shown in a simple SES/SHB Ditch example. The larger model is discussed in the Tailing Impoundment and Mine Pit example.

Below is an example of a file that can be imported using the plug in SES tab to setup SES:

SES
GROUP
#1,1,0,0
XML,[ModelIEPath]DitchElements.xml
0.0,50.0,44,20
#2,1,1,0,0.00,3,1.00
XML,[ModelIEPath]PileElements.xml
100.0,150.0,20,44.0


Alternatively, two GROUP sections can be used:

SES
GROUP
#1,1,0,0
XML,[ModelIEPath]DitchElements.xml
0.0,50.0,44,20
GROUP
#2,1,1,0,0.00,3,1.00
XML,[ModelIEPath]PileElements.xml
100.0,150.0,20,44.0


SES Output Log

During a FEFLOW simulation, SES will display messages in FEFLOW's "Log" panel regarding activation and/or inactivation of elements and amounts of water added to or removed from the groundwater system (if using a Windows "CMD" window to run a simulation, SES will display the messages in that window).

If requested by the user, SES will record simulation data to a separate log file. Output can be logged for every element change. A summary is also recorded at the end of every time-step. This is a comma-delimited text file that can grow very large, especially if detailed changes are logged. This file will contain up to five general types of information:

ACTIVATE,GROUPID,EID,TIME,ELF,ELEM_TRIGGER_ELEV,TRIGGER_OPTION,TARGET_ELEV,WATVOL_CHG

INACTIVATE,GROUPID,EID,TIME,ELF,ELEM_TRIGGER_ELEV,TRIGGER_OPTION,TARGET_ELEV,WATVOL_CHG

RECHARGE,GROUPID,EID,TIME,ELF,NEW_RCH_RATE

ACTIVATED_SUMMARY,GROUPID,NUM_ELEMS,TIME,ELF,SUM_WATVOL_CHG

INACTIVATED_SUMMARY,GROUPID,NUM_ELEMS,TIME,ELF,SUM_WATVOL_CHG

Following these header lines, the beginning of each entry will reference the first word of one of the header lines. For example:

...

INACTIVATE,1,512,29.270756,E,30,1,29.65637,-2.1316041

RECHARGE,1,512,29.270756,E,0

INACTIVATED_SUMMARY,1,20,29.270756,E,4,-0.031204363

INACTIVATE,1,613,39.287375,E,25,1,24.975622,-2.6623225

RECHARGE,1,613,39.287375,E,0

INACTIVATE,1,615,39.287375,E,25,1,24.975622,-3.1857562

RECHARGE,1,615,39.287375,E,0

...

INACTIVATED_SUMMARY,1,8,39.287375,E,-21.29858

...

ACTIVATE,2,677,100.2007,E,22.5,1,22.589282,3.6621095

RECHARGE,2,677,100.2007,E,2.217650

ACTIVATE,2,679,100.2007,E,22.5,1,22.589282,3.6621095

RECHARGE,2,679,100.2007,E,2.217650

...

ACTIVATED_SUMMARY,2,8,100.2007,E,29.296876

...

Where:

ACTIVATE is a keyword indicating that the information on the line is for an element that has been activated by SES

GROUPID is the user-specified integer identifier of the SES GROUP to which the element belongs

TIME is the time at the beginning of the time step when the activity state of the element is flipped. Note that in a FEFLOW result file (DAR or DAC), the simulation time represents results at the end of the current time step. If the element is activated early due to FEFLOW's time-stepping scheme, the TIME will be earlier than anticipated (see ELF).

ELF is a flag that indicates whether or not there was a timing issue for flipping the activity state of an element: "E" means the element was switched on or off early, "0" means there was no timing issue, and "L" means the element was switched on or off late. This flag also applies to changes to recharge related to element activity. Timing issues arise when FEFLOW's automatic time-stepping is used and FEFLOW changes its time-stepping to improve numerical stability. SES cannot determine in advance when FEFLOW will change its timing schedule and so SES may switch on (or off) an element sooner (or later) than expected at an elevation that is lower (or higher) than expected. To evaluate the impact of any timing issues, the switching schedule in the SES log file can be compared to the schedule specified in the SES configuration file.

INACTIVATE is a keyword indicating that the information on the line is for an element that has been inactivated by SES

EID is FEFLOW's integer identifier of the element (index starting at 1) activated or inactivated

ELEM_TRIGGER_ELEV is the current SES elevation for the element for flipping the element's state of activity

TRIGGER_OPTION is the selected trigger option

RECHARGE is a keyword indicating that the information on the line is for an element over which recharge has been modified by SES

NEW_RCH_RATE is the elemental recharge rate assigned by SES

TARGET_ELEV is the current SES elevation of GROUP = GROUPID. If the element is activated early due to time-stepping scheme, the SES elevation will be higher than anticipated (see ELF).

WATVOL_CHG is the volume of water added to (activation) or removed from (inactivation) the model at the end of the current FEFLOW time step

NUM_ELEMS is the number of SES elements that were either activated or inactivated at time = TIME

ACTIVATED_SUMMARY is a keyword indicating that the information on the line summarizes activation data (over all element sets and groups) for the time step

INACTIVATED_SUMMARY is a keyword indicating that the information on the line summarizes inactivation data (over all element sets and groups) for the time step

SUM_WATVOL_CHG is a summation of WATVOL_CHG values at the end of the current FEFLOW time step

Log Parser

Because the different record types in the log file are intermixed, and the log file can be very large, a parser program, LogParser.exe, is included with FFTools. This is a "command line" utility that will copy the SES log data to multiple ASCII (text) files, one file for each Keyword (ACTIVATE, INACTIVATE, RECHARGE, etc.). The new files will be located in the same folder as the parser. To use the program, copy it into the folder containing the SES output log, then, in a command window open to the same folder, type:

LogParser.exe -l SES_Log_File_Name.log

Where "SES_Log_File_Name.log" is the name of the log file created by SES.