Class FWSimComponent
java.lang.Object
net.simplace.sim.model.FWSimComponent
- All Implemented Interfaces:
FWSimFieldContainer
- Direct Known Subclasses:
DefaultManagement, FWAnalyticsSimComponent, FWSimComponentGroup, FWSimpleSimComponent
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.
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enumPhases of a component unit test. -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected HashMap<String, FWSimVariable<?>> Field map as created by thecreateVariables()method of the implementation; shared by all instancesprotected FWSimIOAdapter.FREQUENCEFrequency of execution (default: daily)Links of the inputs: map from input variable name to the name of the linked source variableprotected JexlRuleScriptRule deciding whether the component is executed (for frequency COMPLEX or BOOLEAN)protected FWSimComponentGroupThe component group this component is part of, ornullprotected StringName (id) of the componentprotected intPosition of the component in the order of executionprotected booleantrueif 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 (attributeinactive="reset", #323), so a switched off module does not keep its last values.protected final booleantrueif this component is a component groupprotected org.jdom2.ElementThesimcomponentconfiguration element of the solutionprotected FWSimModelThe model (simulation) this instance belongs toprotected FWSimVarMapThe var map of the simulation this instance belongs to -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedDefault constructor, used to create components by class name (seecreateSimComponent(String)).protectedFWSimComponent(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 theclone(FWSimVarMap)implementations. -
Method Summary
Modifier and TypeMethodDescriptionvoidaddVariable(FWSimVariable<?> aVariable) Adds a variable to the field map.protected voidbind()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.voidcheckCondition(Boolean aCheckResult, String aMessage) Checks a condition during initialisation and reports a failed check according to the check level of the session.protected abstract FWSimComponentclone(FWSimVarMap aVarMap) Creates the instance of this component for a new simulation (usually via the protected clone constructor).static FWSimComponentcreateSimComponent(String aClassname) Instantiates a SimComponent class with its default constructor.static FWSimComponentcreateSimComponent(String tName, FWSimVarMap aVarMap, FWSimModel aSimModel, int aOrderNumber) Creates a SimComponent by class name without configuration element (e.g.static FWSimComponentcreateSimComponent(org.jdom2.Element aSimComponentElement, FWSimComponentGroup aComponentGroup, FWSimVarMap aVarMap, FWSimModel aSimModel, int aOrderNumber) Creates a SimComponent from its configuration element: instantiates the class, creates the variables, registers them in the var map and reads the inputs.static FWSimComponentcreateSimComponent(org.jdom2.Element aSimComponentElement, FWSimVarMap aVarMap, FWSimModel aSimModel, int aOrderNumber) Creates a SimComponent from its configuration element.abstract HashMap<String, FWSimVariable<?>> Creates the variables (constants, inputs, states, rates, outputs) of the component and adds them to the field map (seeaddVariable(FWSimVariable)).protected voidCalled by the model once per time step: checks the frequency (and rule) of the component, callsprocess()if the component is due, and measures the run time.abstract HashMap<String, FWSimVariable<?>> fillTestVariables(int aTestIndex, FWSimComponent.TEST_STATE aDefineOrCheck) Provides the values of a component unit test.final org.jdom2.ElementCreates the GUI form for this component: name, class and a choice of the variables, each with its form fields.org.jdom2.ElementgetEditFormXML(boolean aEnabled) Creates the GUI form for this component (same asgetCreateFormXML()).HashMap<String, FWSimVariable<?>> getInputValueText(String aInputId) getName()intorg.jdom2.ElementgetVariable(String aKey) Returns a variable of this component from the var map of the simulation.protected FWSimVariable<?> getVariableField(String aKey) protected abstract voidinit()Initialization of the implementation, e.g.voidbooleanprotected booleanisVariableAvailable(String aString) voidEstablishes the links defined in theinputelements of the configuration.protected voidperformLinks(HashMap<String, String> aLinkMap) Establishes links in the var map.protected abstract voidprocess()The main calculation of the component.readInputs(org.jdom2.Element aSimComponentElement) Reads theinputelements of the configuration.voidremoveVariable(String aID) Remove variable from FieldMap - handle with care!protected voidreset(FWSimVarMap aVarMap) Prepares the component for the next simulation by setting its var map.static BooleanrunComponentTest(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 oneprocess()and compares the calculated outputs with the expected values (FWSimComponent.TEST_STATE.CHECK).voidsetInputValue(String aInputId, String aValue) Sets or removes the value of an input in the configuration and in the template (e.g.protected voidResets all output variables (outputs, states, rates) of this component in the var map to their default values.protected voidsyncInputLinks(org.jdom2.Element aElement) Brings theinputlinks 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 lastinput(beforeprocess/integrate, see the DTD).org.jdom2.ElementCreates a template of thesimcomponentsection for this component, for inclusion into solutions: constants are linked to the resource generated bytoResourcesDefinitionXML(), inputs get an empty source to be filled in.org.jdom2.ElementtoDocXML()Creates the documentation XML of the component: asimcomponentelement with the definitions of all its variables, sorted by content type and name.org.jdom2.ElementtoGroupXML(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.org.jdom2.ElementCreates a template of anoutputsection for the outputs of this component, for inclusion into solutions: oneoutelement per output variable (name without prefix) plus an id field.org.jdom2.Elementorg.jdom2.ElementCreates a template of aresourcesection for the inputs of this component, for inclusion into solutions: onereselement per input (name without prefix) plus a key field.toString()org.jdom2.ElementtoXML()Creates the configuration element of the component as used in a solution.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.
-
Field Details
-
iName
Name (id) of the component -
iVarMap
The var map of the simulation this instance belongs to -
iFieldMap
Field map as created by thecreateVariables()method of the implementation; shared by all instances -
iInputMap
-
iSimModel
The model (simulation) this instance belongs to -
iSimComponentElement
protected org.jdom2.Element iSimComponentElementThesimcomponentconfiguration element of the solution -
iOrderNumber
protected int iOrderNumberPosition of the component in the order of execution -
iFrequence
Frequency of execution (default: daily) -
iJexlRule
Rule deciding whether the component is executed (for frequency COMPLEX or BOOLEAN) -
iResetWhenInactive
protected boolean iResetWhenInactivetrueif 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 (attributeinactive="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 ofinit()), 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 isComponentGrouptrueif this component is a component group -
iMasterComponentGroup
The component group this component is part of, ornull
-
-
Constructor Details
-
FWSimComponent
protected FWSimComponent()Default constructor, used to create components by class name (seecreateSimComponent(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 theclone(FWSimVarMap)implementations. Frequency and rule are read from the configuration element.- Parameters:
aName- name of the componentaFieldMap- the shared field mapaInputMap- the links of the inputsaSimComponentElement- the configuration elementaVarMap- var map of the new simulationaOrderNumber- 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- thesimcomponentelement (attributeclassis the implementing class)aVarMap- var map of the template modelaSimModel- the model the component belongs toaOrderNumber- 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- thesimcomponentelement (attributeclassis the implementing class)aComponentGroup- the component group the component is part of, ornullaVarMap- var map of the template modelaSimModel- the model the component belongs toaOrderNumber- 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 nameaVarMap- var mapaSimModel- the model the component belongs toaOrderNumber- position in the order of execution- Returns:
- the new component
- Throws:
SimLinkInvalidException- if the component cannot be created
-
createSimComponent
Instantiates a SimComponent class with its default constructor. Variables are not created.- Parameters:
aClassname- fully qualified class name- Returns:
- the new instance, or
nullif the class is abstract or cannot be instantiated (an error is logged)
-
getVariableField
- Parameters:
aKey- full name of the variable- Returns:
- the variable from the (shared) field map - not from the var map of the simulation!
-
isVariableAvailable
- Parameters:
aString- name of the variable- Returns:
trueif the variable exists in the var map and has a non-empty value
-
addVariable
Adds a variable to the field map. Call this increateVariables()of the implementation.- Specified by:
addVariablein interfaceFWSimFieldContainer- Parameters:
aVariable- the variable to add
-
getVariable
Returns a variable of this component from the var map of the simulation. Plain names are prefixed with the component name; names starting withCURRENT.or containing a dot are looked up directly (the latter with a warning).- Specified by:
getVariablein interfaceFWSimFieldContainer- Parameters:
aKey- name of the variable, usually without component name- Returns:
- the variable
- Throws:
SimFieldMissingException- if the variable does not exist
-
removeVariable
Remove variable from FieldMap - handle with care!- Specified by:
removeVariablein interfaceFWSimFieldContainer- Parameters:
aID- id of the variable- See Also:
-
getName
- Specified by:
getNamein interfaceFWSimFieldContainer- Returns:
- the name
-
getFieldMap
- Specified by:
getFieldMapin interfaceFWSimFieldContainer- Returns:
- the field map created by
createVariables()
-
getVarMap
- Specified by:
getVarMapin interfaceFWSimFieldContainer- Returns:
- the var map this container belongs to
-
getFrequenceRuleScript
- Returns:
- the rule deciding whether the component is executed (frequency COMPLEX or BOOLEAN), or
null
-
readInputs
Reads theinputelements of the configuration. An input with asourceattribute 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
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.xmlto, ornullto only return the XML- Returns:
- the XML string, or
nullif 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.LUEforcLUE) of type FWSimVariable is set to the variable of this simulation. Component groups bind their members. Called byinitialize(). -
initialize
-
init
protected abstract void init()Initialization of the implementation, e.g. setting initial state values. Called once per simulation before the first call ofprocess(); 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
Creates the variables (constants, inputs, states, rates, outputs) of the component and adds them to the field map (seeaddVariable(FWSimVariable)). Called only once when the component is created.- Specified by:
createVariablesin interfaceFWSimFieldContainer- Returns:
- the field map
- See Also:
-
performLinks
Establishes the links defined in theinputelements of the configuration. Done only once while the model is created.- Throws:
SimLinkInvalidException- if a link is invalid (e.g. different data types)
-
performLinks
Establishes links in the var map. Inputs with unitFWSimVariable.UNIT_SOLUTION_DEFINEDtake the unit of the linked variable, outputs set up withFWSimVariable.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
-
reset
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, callsprocess()if the component is due, and measures the run time. If it is not due and the component hasinactive="reset", its outputs are reset to their defaults (#323).Switching between modules:
frequence="COMPLEX" rule="${CURRENT.DOY} le 180"(expression) orfrequence="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
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
- Specified by:
getInputVariablesin interfaceFWSimFieldContainer- Returns:
- the input variables (inputs, constants, private variables) from the field map
- See Also:
-
getConstantVariables
- Returns:
- the constants from the field map
-
getOutputVariables
- Specified by:
getOutputVariablesin interfaceFWSimFieldContainer- Returns:
- the output variables (outputs, states, rates) from the field map
- See Also:
-
toString
-
toDocXML
public org.jdom2.Element toDocXML()Creates the documentation XML of the component: asimcomponentelement 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 theinputlinks brought up to date (seesyncInputLinks(Element)); a component created without element getsinputelements for all links and for all values that differ from the default value.- Specified by:
toXMLin interfaceFWSimFieldContainer- Returns:
- an XML element with all settings of this container
- See Also:
-
getSimComponentElement
public org.jdom2.Element getSimComponentElement()- Returns:
- the
simcomponentconfiguration element, ornullfor a component created without element
-
syncInputLinks
protected void syncInputLinks(org.jdom2.Element aElement) Brings theinputlinks 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 lastinput(beforeprocess/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
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 theinputelement; an empty value removes the element and resets the variable to its default. Linked inputs are changed withFWSimSolution.setInputSource(FWSimComponent, String, String).- Parameters:
aInputId- id of the input (without component name)aValue- the value as text, ornull/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
-
toGroupXML
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 groupaGroupName- 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 aresourcesection for the inputs of this component, for inclusion into solutions: onereselement per input (name without prefix) plus a key field.- Returns:
- the
resourceelement
-
toOutputDefinitionXML
public org.jdom2.Element toOutputDefinitionXML()Creates a template of anoutputsection for the outputs of this component, for inclusion into solutions: oneoutelement per output variable (name without prefix) plus an id field.- Returns:
- the
outputelement
-
toComponentLinkingXML
public org.jdom2.Element toComponentLinkingXML()Creates a template of thesimcomponentsection for this component, for inclusion into solutions: constants are linked to the resource generated bytoResourcesDefinitionXML(), inputs get an empty source to be filled in.- Returns:
- the
simcomponentelement
-
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:
getCreateFormXMLin interfaceFWSimFieldContainer- 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 asgetCreateFormXML()). 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:
getEditFormXMLin interfaceFWSimFieldContainer- Parameters:
aEnabled- iffalse, 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:
getOrderNumberin interfaceFWSimFieldContainer- Returns:
- position of this container in the order of execution
- See Also:
-
getContentType
- Specified by:
getContentTypein interfaceFWSimFieldContainer- Returns:
- the content type of the variables of this container (e.g.
sys,mgm) - See Also:
-
getFrequence
- Specified by:
getFrequencein interfaceFWSimFieldContainer- Returns:
- the frequency in which this container is called, or
nullif not applicable - See Also:
-
getMasterComponentGroup
- Returns:
- the component group this component is part of, or
null
-
getDescription
- Returns:
- the text of the
descriptionelement of the configuration, with its title in bold (HTML), ornullif there is no description
-
runComponentTest
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 oneprocess()and compares the calculated outputs with the expected values (FWSimComponent.TEST_STATE.CHECK).- Parameters:
aComponentClassName- fully qualified class name of the componentaTestIndex- number of the test case, starting with 0- Returns:
trueif all outputs match,falseotherwise (differences are logged with level DEBUG),nullif 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 0aDefineOrCheck- phase:FWSimComponent.TEST_STATE.DEFINEfor the input values,FWSimComponent.TEST_STATE.STATEfor the state values,FWSimComponent.TEST_STATE.CHECKfor the expected output values- Returns:
- the field map, or
nullif there is no test case with this index - See Also:
-
checkCondition
Description copied from interface:FWSimFieldContainerChecks a condition during initialisation and reports a failed check according to the check level of the session.- Specified by:
checkConditionin interfaceFWSimFieldContainer- Parameters:
aCheckResult- result of the check;falsemeans the condition is violatedaMessage- message describing the condition- See Also:
-
isConditionCheck
public boolean isConditionCheck()- Specified by:
isConditionCheckin interfaceFWSimFieldContainer- Returns:
trueif conditions are checked with the current check level of the session- See Also:
-