Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Painfully Simple Form
A Painfully Simple Form in ICE is a Form that was created by parsing Entries and DataComponents from a file written in the Painfully Simple Form File Format
Contents
The Painfully Simple Form File Format
The Painfully Simple Form file format (PSF) was designed to be overly simple for developers who are hooking their codes to ICE and painfully simple to parse. It is mostly the same as an ini file or a Java properties file, but with small differences that make it specific to ICE.
Comments
Any text after a "#" or "//" will be ignored by the parser whether it is a line of text commenting on a section or comments after a statement.
#Ignored text above a block group=My Group //Ignored text after a statement groupDescription=My Group #More ignored text
Whitespace
Empty lines are required between blocks. Whitespace within statements is kept (because all statements are treated as strings).
Item type and name
The name, description, and type of the Form should be the first thing specified in the PSF. At the moment, Item type should be either Model or Simulation.
#Form name, description and type formName=PSF Wiki Article Form formDescription A PSF Wiki Article Sample formType=Model
DataComponents
ICE DataComponents are collections of Entries and they can be described in a PSF. The "group=" statement is used to create a DataComponent and the "groupDescription=" tag is used to describe it. Both the name and description must be present or ICE will not read the file. All of the DataComponents should be specified in a block above the Entries.
#The DataComponents block group=1st Data Component groupDescription=The First Data Component group=2nd Data Component groupDescription=The Second Data Component group=Black Sabbath Songs groupDescription=A group of songs written and performed by the popular band "Black Sabbath" #The Entry blocks will appear below this line
Entries
The ICE Entry class represents a value in a data file and contains a "full description" of that data, including a name, description, and default value among other things. It is possible to specify any Entry in a psf file, but these Entries will not have tailored setup() and update() operations. The name and description statements can be any string and there may be multiple allowed values for each Entry, depending on its type. The allowedValueType is the same as that for an Entry and has three possible values:
- Discrete, meaning that the value of the Entry must be one of the allowed values
- Continuous, meaning that it is a floating point number that is valid between the two allowed values (which also means that you can only have two allowed values)
- Undefined, meaning that it can be anything, like a string or a file name.
Entry with a small marker or note that could be used, for example, to correlate it with some external source or markup.
Each Entry needs to be added to a DataComponent using the group= flag. This should be one of the groups listed in the groups block. If it is not one of the predefined groups, or if it is missing all together, this Entry will be discarded.
Here's an example with two Entries, one discrete and one continuous:
name=Coolant Temperature //The name that a user will see description=The temperature of the coolant that surrounds the assembly and pins //A description that will help the user defaultValue=550 //The default value allowedValueType=Continuous //Indicates that the value can be anything between 550 and 650 K. allowedValue=550 //The lower bound of the range allowedValue=650 //The upper bound of the range tag=coolantTemperature //A tag to mark it group=Coolant Group //The group name=Number of Pins description=The number of pins in an assembly defaultValue=289 allowedValueType=Discrete allowedValue=196 allowedValue=289 tag=numberOfPins group=Pin Group
Entries can also claim that they are dependent on the state of another Entry. The PSF natively supports a boolean dependency, where Entries can mark themselves as dependent on the on/off state of a parent Entry. When the parent flips between on/off states, the child will automatically be notified. The catch here is that the parent must be a boolean query ("Enable multiprocessing: y/n" for example) and that the value of that parent is one of:
- not ready
- yes
- no
- y
- n
- on
- off
- true
- false
- enabled
- disabled
Parents are distinguished using the parent statement and the name of the parent as the value. Here's an example of two Entries that are dependent on a third such Entry:
name=Coolant Temperature //The name that a user will see description=The temperature of the coolant that surrounds the assembly and pins //A description that will help the user defaultValue=550 //The default value allowedValueType=Continuous //Indicates that the value can be anything between 550 and 650 K. allowedValue=550 //The lower bound of the range allowedValue=650 //The upper bound of the range tag=coolantTemperature //A tag to mark it parent=Full Assembly Flag //The parent group=Assembly //The group name=Number of Pins description=The number of pins in an assembly defaultValue=289 allowedValueType=Discrete allowedValue=196 allowedValue=289 tag=numberOfPins parent=Full Assembly Flag group=Assembly name=Full Assembly Flag description=True if a full assembly should be modeled, false if not defaultValue=false allowedValueType=Discrete allowedValue=true allowedValue=false tag=fullAssemblyFlag group=Assembly
A Complete File
Here's a complete file created using the examples from the previous two sections. This is a 100% valid file, but if you find a mistake, let us know!
#Form name, description and type formName=PSF Wiki Article Form formDescription=A PSF Wiki Article Sample formType=Model #The DataComponents block - it must come first! group=Coolant Group groupDescription=Data Entries that describe coolant properties group=Pin Group groupDescription=Data Entries that describe the properties of fuel pins #The Entry blocks will appear below this line name=Coolant Temperature //The name that a user will see description=The temperature of the coolant that surrounds the assembly and pins //A description that will help the user defaultValue=550 //The default value allowedValueType=Continuous //Indicates that the value can be anything between 550 and 650 K. allowedValue=550 //The lower bound of the range allowedValue=650 //The upper bound of the range tag=coolantTemperature //A tag to mark it group=Coolant Group //The group name=Number of Pins description=The number of pins in an assembly defaultValue=289 allowedValueType=Discrete allowedValue=196 allowedValue=289 tag=numberOfPins group=Pins Group
A Complete File with Dependencies
Here's a complete file created using the examples from the previous two sections. This is a 100% valid file, but if you find a mistake, let us know!
#Form name, description and type formName=PSF Wiki Article Form formDescription=A PSF Wiki Article Sample formType=Model #The DataComponents block - it must come first! group=Assembly groupDescription=Relevant quantities for modeling a full assembly #The Entry blocks will appear below this line name=Coolant Temperature //The name that a user will see description=The temperature of the coolant that surrounds the assembly and pins //A description that will help the user defaultValue=550 //The default value allowedValueType=Continuous //Indicates that the value can be anything between 550 and 650 K. allowedValue=550 //The lower bound of the range allowedValue=650 //The upper bound of the range tag=coolantTemperature //A tag to mark it parent=Full Assembly Flag //The parent group=Assembly //The group name=Number of Pins description=The number of pins in an assembly defaultValue=289 allowedValueType=Discrete allowedValue=196 allowedValue=289 tag=numberOfPins parent=Full Assembly Flag group=Assembly name=Full Assembly Flag description=True if a full assembly should be modeled, false if not defaultValue=false allowedValueType=Discrete allowedValue=true allowedValue=false tag=fullAssemblyFlag group=Assembly