Class FWSimComponent

java.lang.Object
net.simplace.sim.model.FWSimComponent
All Implemented Interfaces:
FWSimFieldContainer
Direct Known Subclasses:
DefaultManagement, FWAnalyticsSimComponent, FWSimComponentGroup, FWSimpleSimComponent

public abstract class FWSimComponent extends Object implements FWSimFieldContainer
Base class of all SimComponents - the smallest unit of a model, containing the algorithms of the scientific model.

An implementation has to provide:

  • createVariables(): creates the constants, inputs, states, rates and outputs of the component,
  • init(): initialises the component at the start of a simulation,
  • process(): calculates one time step,
  • clone(FWSimVarMap): creates the instance for a new simulation.
The component is configured by a simcomponent element of the solution, which defines the class, the id, optionally the frequency (and rule) of execution, and the input elements (values or links to other variables). Each component should be documented in detail and have its own unit test.
Author:
Andreas Enders
  • Field Details

    • iName

      protected String iName
      Name (id) of the component
    • iVarMap

      protected FWSimVarMap iVarMap
      The var map of the simulation this instance belongs to
    • iFieldMap

      protected HashMap<String, FWSimVariable<?>> iFieldMap
      Field map as created by the createVariables() method of the implementation; shared by all instances
    • iInputMap

      protected HashMap<String,String> iInputMap
      Links of the inputs: map from input variable name to the name of the linked source variable
    • iSimModel

      protected FWSimModel iSimModel
      The model (simulation) this instance belongs to
    • iSimComponentElement

      protected org.jdom2.Element iSimComponentElement
      The simcomponent configuration element of the solution
    • iOrderNumber

      protected int iOrderNumber
      Position of the component in the order of execution
    • iFrequence

      protected FWSimIOAdapter.FREQUENCE iFrequence
      Frequency of execution (default: daily)
    • iJexlRule

      protected JexlRuleScript iJexlRule
      Rule deciding whether the component is executed (for frequency COMPLEX or BOOLEAN)
    • iResetWhenInactive

      protected boolean iResetWhenInactive
      true if the outputs (outputs, states, rates) are reset to their defaults in every step in which the component is not executed because of its frequency or rule (attribute inactive="reset", #323), so a switched off module does not keep its last values. Default (inactive="keep"): the values are kept. Note: states and outputs used as internal state are reset, too (not to the values of init()), so a component that is switched on again afterwards may fail or start from the defaults; use it for modules that stay switched off or calculate everything from their inputs in each step.
    • isComponentGroup

      protected final boolean isComponentGroup
      true if this component is a component group
    • iMasterComponentGroup

      protected FWSimComponentGroup iMasterComponentGroup
      The component group this component is part of, or null
  • Constructor Details

    • FWSimComponent

      protected FWSimComponent()
      Default constructor, used to create components by class name (see createSimComponent(String)).
    • FWSimComponent

      protected FWSimComponent(String aName, HashMap<String, FWSimVariable<?>> aFieldMap, HashMap<String,String> aInputMap, org.jdom2.Element aSimComponentElement, FWSimVarMap aVarMap, int aOrderNumber)
      Creates a component for a new simulation; called from the clone(FWSimVarMap) implementations. Frequency and rule are read from the configuration element.
      Parameters:
      aName - name of the component
      aFieldMap - the shared field map
      aInputMap - the links of the inputs
      aSimComponentElement - the configuration element
      aVarMap - var map of the new simulation
      aOrderNumber - position in the order of execution
  • Method Details

    • createSimComponent

      public static FWSimComponent createSimComponent(org.jdom2.Element aSimComponentElement, FWSimVarMap aVarMap, FWSimModel aSimModel, int aOrderNumber) throws SimLinkInvalidException
      Creates a SimComponent from its configuration element.
      Parameters:
      aSimComponentElement - the simcomponent element (attribute class is the implementing class)
      aVarMap - var map of the template model
      aSimModel - the model the component belongs to
      aOrderNumber - position in the order of execution
      Returns:
      the new component
      Throws:
      SimLinkInvalidException - if the component cannot be created
    • createSimComponent

      public static FWSimComponent createSimComponent(org.jdom2.Element aSimComponentElement, FWSimComponentGroup aComponentGroup, FWSimVarMap aVarMap, FWSimModel aSimModel, int aOrderNumber) throws SimLinkInvalidException
      Creates a SimComponent from its configuration element: instantiates the class, creates the variables, registers them in the var map and reads the inputs.
      Parameters:
      aSimComponentElement - the simcomponent element (attribute class is the implementing class)
      aComponentGroup - the component group the component is part of, or null
      aVarMap - var map of the template model
      aSimModel - the model the component belongs to
      aOrderNumber - position in the order of execution
      Returns:
      the new component
      Throws:
      SimLinkInvalidException - if the component cannot be created
    • createSimComponent

      public static FWSimComponent createSimComponent(String tName, FWSimVarMap aVarMap, FWSimModel aSimModel, int aOrderNumber) throws SimLinkInvalidException
      Creates a SimComponent by class name without configuration element (e.g. a new component in the graph panel): the name is the simple class name, there is no frequency, rule or input.
      Parameters:
      tName - fully qualified class name
      aVarMap - var map
      aSimModel - the model the component belongs to
      aOrderNumber - position in the order of execution
      Returns:
      the new component
      Throws:
      SimLinkInvalidException - if the component cannot be created
    • createSimComponent

      public static FWSimComponent createSimComponent(String aClassname)
      Instantiates a SimComponent class with its default constructor. Variables are not created.
      Parameters:
      aClassname - fully qualified class name
      Returns:
      the new instance, or null if the class is abstract or cannot be instantiated (an error is logged)
    • getVariableField

      protected FWSimVariable<?> getVariableField(String aKey)
      Parameters:
      aKey - full name of the variable
      Returns:
      the variable from the (shared) field map - not from the var map of the simulation!
    • isVariableAvailable

      protected boolean isVariableAvailable(String aString)
      Parameters:
      aString - name of the variable
      Returns:
      true if the variable exists in the var map and has a non-empty value
    • addVariable

      public void addVariable(FWSimVariable<?> aVariable)
      Adds a variable to the field map. Call this in createVariables() of the implementation.
      Specified by:
      addVariable in interface FWSimFieldContainer
      Parameters:
      aVariable - the variable to add
    • getVariable

      public FWSimVariable<?> getVariable(String aKey) throws SimFieldMissingException
      Returns a variable of this component from the var map of the simulation. Plain names are prefixed with the component name; names starting with CURRENT. or containing a dot are looked up directly (the latter with a warning).
      Specified by:
      getVariable in interface FWSimFieldContainer
      Parameters:
      aKey - name of the variable, usually without component name
      Returns:
      the variable
      Throws:
      SimFieldMissingException - if the variable does not exist
    • removeVariable

      public void removeVariable(String aID)
      Remove variable from FieldMap - handle with care!
      Specified by:
      removeVariable in interface FWSimFieldContainer
      Parameters:
      aID - id of the variable
      See Also:
    • getName

      public String getName()
      Specified by:
      getName in interface FWSimFieldContainer
      Returns:
      the name
    • getFieldMap

      public HashMap<String, FWSimVariable<?>> getFieldMap()
      Specified by:
      getFieldMap in interface FWSimFieldContainer
      Returns:
      the field map created by createVariables()
    • getVarMap

      public FWSimVarMap getVarMap()
      Specified by:
      getVarMap in interface FWSimFieldContainer
      Returns:
      the var map this container belongs to
    • getFrequenceRuleScript

      public JexlRuleScript getFrequenceRuleScript()
      Returns:
      the rule deciding whether the component is executed (frequency COMPLEX or BOOLEAN), or null
    • readInputs

      protected HashMap<String,String> readInputs(org.jdom2.Element aSimComponentElement)
      Reads the input elements of the configuration. An input with a source attribute is a link to another variable; an input with a text sets the value (and, in the template, the default value) of the variable.
      Parameters:
      aSimComponentElement - the configuration element
      Returns:
      map from input variable name to the name of the linked source variable
      Throws:
      SimFieldMissingException - if an input refers to a variable that the component does not have
    • writeVarInfos

      public String writeVarInfos(String aFilePath)
      Creates the variables and writes their definitions (content type, id, description, unit, default, limits, rule, mode, data type) as XML, e.g. for documentation.
      Parameters:
      aFilePath - directory to write <ClassName>_configuration.xml to, or null to only return the XML
      Returns:
      the XML string, or null if writing failed
    • bind

      protected void bind()
      Binds the variables of the var map to the fields of the implementing class: for each variable, a class field with the same name (or the name without content type prefix, e.g. LUE for cLUE) of type FWSimVariable is set to the variable of this simulation. Component groups bind their members. Called by initialize().
    • initialize

      public void initialize()
      Initializes the component at the start of a simulation: binds the variables to the class fields (see bind()) and calls init(). Called once per simulation before the first time step.
    • init

      protected abstract void init()
      Initialization of the implementation, e.g. setting initial state values. Called once per simulation before the first call of process(); the variables are already bound.
    • setVariablesDefault

      protected void setVariablesDefault()
      Resets all output variables (outputs, states, rates) of this component in the var map to their default values.
    • createVariables

      public abstract HashMap<String, FWSimVariable<?>> createVariables()
      Creates the variables (constants, inputs, states, rates, outputs) of the component and adds them to the field map (see addVariable(FWSimVariable)). Called only once when the component is created.
      Specified by:
      createVariables in interface FWSimFieldContainer
      Returns:
      the field map
      See Also:
    • performLinks

      public void performLinks() throws SimLinkInvalidException
      Establishes the links defined in the input elements of the configuration. Done only once while the model is created.
      Throws:
      SimLinkInvalidException - if a link is invalid (e.g. different data types)
    • performLinks

      protected void performLinks(HashMap<String,String> aLinkMap) throws SimLinkInvalidException
      Establishes links in the var map. Inputs with unit FWSimVariable.UNIT_SOLUTION_DEFINED take the unit of the linked variable, outputs set up with FWSimVariable.setUnitFrom(FWSimVariable) then take the unit of their input (#60). With log level TRACE, the units of the linked variables are compared and unlinked inputs are listed.
      Parameters:
      aLinkMap - map with key = destination (input) and value = source variable name
      Throws:
      SimLinkInvalidException - if a link is invalid (e.g. different data types)
    • getInputs

      public Map<String,String> getInputs()
      Returns:
      the links of the inputs: map from input variable name (including component name) to the name of the linked source variable
    • reset

      protected void reset(FWSimVarMap aVarMap)
      Prepares the component for the next simulation by setting its var map.
      Parameters:
      aVarMap - var map of the next simulation
    • doProcess

      protected void doProcess()
      Called by the model once per time step: checks the frequency (and rule) of the component, calls process() if the component is due, and measures the run time. If it is not due and the component has inactive="reset", its outputs are reset to their defaults (#323).

      Switching between modules: frequence="COMPLEX" rule="${CURRENT.DOY} le 180" (expression) or frequence="BOOLEAN" rule="vUseA" (name of a boolean variable) switches a module on or off per step; a FWSimpleSimComponent after the alternatives (rule ${vUseA} ? ${A.x} : ${B.x}) gives the value of the active one to the following components (example: solution framework/ModuleSwitch.sol.xml in simplace_modules/test).

    • process

      protected abstract void process()
      The main calculation of the component. Called once per time step in which the component is due (see its frequency).
    • clone

      protected abstract FWSimComponent clone(FWSimVarMap aVarMap)
      Creates the instance of this component for a new simulation (usually via the protected clone constructor).
      Parameters:
      aVarMap - var map of the new simulation
      Returns:
      the new instance
    • getInputVariables

      public ArrayList<FWSimVariable<?>> getInputVariables()
      Specified by:
      getInputVariables in interface FWSimFieldContainer
      Returns:
      the input variables (inputs, constants, private variables) from the field map
      See Also:
    • getConstantVariables

      public ArrayList<FWSimVariable<?>> getConstantVariables()
      Returns:
      the constants from the field map
    • getOutputVariables

      public ArrayList<FWSimVariable<?>> getOutputVariables()
      Specified by:
      getOutputVariables in interface FWSimFieldContainer
      Returns:
      the output variables (outputs, states, rates) from the field map
      See Also:
    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      the name of the component
    • toDocXML

      public org.jdom2.Element toDocXML()
      Creates the documentation XML of the component: a simcomponent element with the definitions of all its variables, sorted by content type and name.
      Returns:
      the documentation element
    • toXML

      public org.jdom2.Element toXML()
      Creates the configuration element of the component as used in a solution. A component read from a solution returns a copy of its configuration element (keeping frequency, rule, description and comments) with the input links brought up to date (see syncInputLinks(Element)); a component created without element gets input elements for all links and for all values that differ from the default value.
      Specified by:
      toXML in interface FWSimFieldContainer
      Returns:
      an XML element with all settings of this container
      See Also:
    • getSimComponentElement

      public org.jdom2.Element getSimComponentElement()
      Returns:
      the simcomponent configuration element, or null for a component created without element
    • syncInputLinks

      protected void syncInputLinks(org.jdom2.Element aElement)
      Brings the input links of a configuration element up to date with the links of this component (getInputs()): a changed source is set, a removed link is deleted, a link replacing a value replaces the value and new links are added after the last input (before process/integrate, see the DTD). Unchanged inputs and values stay as they are (Redmine #62).
      Parameters:
      aElement - the element to update (a copy of the configuration element)
    • setInputValue

      public void setInputValue(String aInputId, String aValue)
      Sets or removes the value of an input in the configuration and in the template (e.g. from the input dialog of the GUI, Redmine #62). The value is written as text of the input element; an empty value removes the element and resets the variable to its default. Linked inputs are changed with FWSimSolution.setInputSource(FWSimComponent, String, String).
      Parameters:
      aInputId - id of the input (without component name)
      aValue - the value as text, or null/empty to remove it
      Throws:
      IllegalArgumentException - if the input does not exist or is an array (arrays are not supported)
      NumberFormatException - if the value cannot be converted
    • getInputValueText

      public String getInputValueText(String aInputId)
      Parameters:
      aInputId - id of the input (without component name)
      Returns:
      the value given as text in the configuration, or null
    • toGroupXML

      public org.jdom2.Element toGroupXML(HashSet<String> aComponentsInGroup, String aGroupName)
      Creates the configuration element of this component as member of a component group: inputs from other members keep their source, all other inputs are taken from the group; linked outputs are published as outputs of the group.
      Parameters:
      aComponentsInGroup - names of all members of the group
      aGroupName - name of the group
      Returns:
      the configuration element
    • toResourcesDataXML

      public org.jdom2.Element toResourcesDataXML()
      Returns:
      xml element with all the info about constants of this component
    • toResourcesDefinitionXML

      public org.jdom2.Element toResourcesDefinitionXML()
      Creates a template of a resource section for the inputs of this component, for inclusion into solutions: one res element per input (name without prefix) plus a key field.
      Returns:
      the resource element
    • toOutputDefinitionXML

      public org.jdom2.Element toOutputDefinitionXML()
      Creates a template of an output section for the outputs of this component, for inclusion into solutions: one out element per output variable (name without prefix) plus an id field.
      Returns:
      the output element
    • toComponentLinkingXML

      public org.jdom2.Element toComponentLinkingXML()
      Creates a template of the simcomponent section for this component, for inclusion into solutions: constants are linked to the resource generated by toResourcesDefinitionXML(), inputs get an empty source to be filled in.
      Returns:
      the simcomponent element
    • getCreateFormXML

      public final org.jdom2.Element getCreateFormXML()
      Creates the GUI form for this component: name, class and a choice of the variables, each with its form fields.
      Specified by:
      getCreateFormXML in interface FWSimFieldContainer
      Returns:
      the XML form definition used by the GUI to create this container
      See Also:
    • getEditFormXML

      public org.jdom2.Element getEditFormXML(boolean aEnabled)
      Creates the GUI form for this component (same as getCreateFormXML()). aEnabled is not needed: the form of an existing component is read-only anyway (the variables are defined by the class, name and class are fixed).
      Specified by:
      getEditFormXML in interface FWSimFieldContainer
      Parameters:
      aEnabled - if false, the form fields are read-only
      Returns:
      the XML form definition used by the GUI to edit the settings of this container
      See Also:
    • getOrderNumber

      public int getOrderNumber()
      Specified by:
      getOrderNumber in interface FWSimFieldContainer
      Returns:
      position of this container in the order of execution
      See Also:
    • getContentType

      public FWSimVariable.CONTENT_TYPE getContentType()
      Specified by:
      getContentType in interface FWSimFieldContainer
      Returns:
      the content type of the variables of this container (e.g. sys, mgm)
      See Also:
    • getFrequence

      public FWSimIOAdapter.FREQUENCE getFrequence()
      Specified by:
      getFrequence in interface FWSimFieldContainer
      Returns:
      the frequency in which this container is called, or null if not applicable
      See Also:
    • getMasterComponentGroup

      public FWSimComponentGroup getMasterComponentGroup()
      Returns:
      the component group this component is part of, or null
    • getDescription

      public String getDescription()
      Returns:
      the text of the description element of the configuration, with its title in bold (HTML), or null if there is no description
    • runComponentTest

      public static Boolean runComponentTest(String aComponentClassName, int aTestIndex)
      Runs a unit test of a single component without simulation: creates the component, sets the test inputs (FWSimComponent.TEST_STATE.DEFINE), initializes it, sets the test states (FWSimComponent.TEST_STATE.STATE), runs one process() and compares the calculated outputs with the expected values (FWSimComponent.TEST_STATE.CHECK).
      Parameters:
      aComponentClassName - fully qualified class name of the component
      aTestIndex - number of the test case, starting with 0
      Returns:
      true if all outputs match, false otherwise (differences are logged with level DEBUG), null if the component defines no test case with this index
      See Also:
    • fillTestVariables

      public abstract HashMap<String, FWSimVariable<?>> fillTestVariables(int aTestIndex, FWSimComponent.TEST_STATE aDefineOrCheck)
      Provides the values of a component unit test. Implementations set the values of their variables depending on the phase.
      Parameters:
      aTestIndex - number of the test case, starting with 0
      aDefineOrCheck - phase: FWSimComponent.TEST_STATE.DEFINE for the input values, FWSimComponent.TEST_STATE.STATE for the state values, FWSimComponent.TEST_STATE.CHECK for the expected output values
      Returns:
      the field map, or null if there is no test case with this index
      See Also:
    • checkCondition

      public void checkCondition(Boolean aCheckResult, String aMessage)
      Description copied from interface: FWSimFieldContainer
      Checks a condition during initialisation and reports a failed check according to the check level of the session.
      Specified by:
      checkCondition in interface FWSimFieldContainer
      Parameters:
      aCheckResult - result of the check; false means the condition is violated
      aMessage - message describing the condition
      See Also:
    • isConditionCheck

      public boolean isConditionCheck()
      Specified by:
      isConditionCheck in interface FWSimFieldContainer
      Returns:
      true if conditions are checked with the current check level of the session
      See Also: