About Expressions in HYPERSIM

HYPERSIM, ScopeView and TestView allow to describe values through variables or mathematical expressions that may or may not refer to other components. These expressions can use regular mathematical symbols (sqrt, ln, pi, e, ...) and component attributes as parameters. 

Define a Parameter as an Expression

To define a parameter as an expression, open the component's parameter form. Eligible parameters are presented as text fields. Press = to open the Content Editor, the tool for editing expressions.

The Analyze expression button computes the expression and checks its validity. If errors are detected, the Ok button is disabled, the text Wrongly written parameter appears and a popup gives details about the error.

The Ok button calls the Analyze expression button in the case it hadn't been executed and applies the value to the field in which the Content Editor was called if there are no errors. While editing the expression, you can use ENTER as a shortcut for the Ok button.

The Cancel button simply closes the window. While editing the expression, you can use ESCAPE as a shortcut for the Cancel button.

Analyze the expression

If the expression is valid:

• If the expression is purely a number (such as 37, -54.7, 3.1415, 0 ...), the expression is not be considered as an expression when copied in the original text field, simply as a number.
• If the expression is purely a mathematical expression with no circuit parameter, the text Nothing to analyze is printed, but the expression is still considered as an expression when clicking Ok.
• If the expression contains circuit component attributes, then a table is printed at the bottom of the Content Editor. When computing the expression, all parameters are replaced by the number in the Value column, all units, prefixes and suffixes are ignored.
• Analyzing the expression will check if the result is a valid number, and if it fits within the parameter's limits

Ok

Once we click Ok with a valid expression, the original text field is updated with the text field's content in the Content Editor. NB: the = is removed when an expression is a pure number. When clicking Apply or Ok in the parameter form, the field turns blue, which indicates that the field value is an expression. Clicking on it automatically opens the content editor again. Now the parameters in the expression and the target parameter are bound: if one change, the target of the expression will be automatically re-evaluated. Clicking on the field will display the extended-expression in the fx: field at the top of the parameter form.

Syntax

• Mathematical expressions: pi, sqrt(37), log(2) (NB: log here is actually ln as some other software), e (=2.718), 3e3 (=3000)
• To get a parameter in the circuit : [ComponentName].[AttributeName], for example =Ld1.vBase
• To get a parameter in a subcircuit : [SubCircuitN].[ComponentName].[AttributeName]. For example, if we wrap Ld2 in a subcircuit DEV1: =DEV1.Ld2.fBase
• The initial = is added in the Content Editor text field if it has been deleted

Limitations

• Expressions currently cannot use most 3-phase parameters. One expects the following syntax Ld1.R[2], but it is not implemented. However, it is possible to define each phase of an attribute with an expression.
• If Comp1.Attr1 = Comp2.A and the component is moved to a subcircuit, then analyzing the expression won't work because the path to the parameter has changed and is not updated automatically.
• It is not recommended to cross-reference expressions, e.g. Comp1.Attr1 = Comp2.A, and then do Comp2.A = Comp1.Attr1.
• If the referenced component name is changed, the expression is not updated.
• The application can crash in extreme cases, e.g. take 4 constants:
  • Master
  • Slave1 = Slave2
  • Slave2 = Slave3
  • Slave3 = Slave1 + Master
  • Changing twice the value of master will result in a fatal error of Java. Then it is not possible to open parameter forms anymore.
• In the Python API, setComponentParameter can be used to set an expression. However, the since the "," symbol is used to split phase or array elements, using an expression with "," does not work. For example "=max(10,5)" will not work via API. The workaround is to replace the "," by ";" in the usage of the API. Therefore, "=max(10;5)" will be corrected by HYPERSIM and evaluated correctly.