Assert (module) - Assert objects can be used to monitor the properties of other objects
Synopsis
module assert; class assert; class double_assert; class complex_assert; class enum_assert;
Assert Overview
The assert class is used purely for validation purposes. They are used to assert that a given parameter will have a certain value at a certain time. In most case, this is used in conjunction with the auto-validation process performed on the nightly builds. More information on the validation process can be found at: Integrated_Testing
Assert Objects
Assert objects work by taking a user defined value and comparing it against a property that is also specified by the user. There are three different assert objects that may be used, complex_assert, double_assert, and enum_assert. These are used to test against complex numbers (r + j*x), double values (real numbers), and enumerations (strings), respectively. Each object also contains a number of operating modes that will further explained below.
To create an assert test, an assert object is created as a child of the object to be tested. Three inputs must be specified to create the assert:
- value - This is the "right" answer, or the value to be checked against, that is provide by the user. The type of value used depends on the type of assert used (complex, double, or enumeration). Units are not used in this value, so must be in the same units as the answer to be compared against.
- within - This allows the user to specify a range of answer. **Not used in enum_assert - value must be the exact string.**
- target - This tells the assert object what value is being tested against. Quotes must encompass the name of the property. Any public variable may be used. The default units of the target property will be used when comparing against value.
Here's an example:
object node {
name test_node_1;
phases ABCN;
nominal_voltage 7200;
voltage_A +7199.558+0.000j;
voltage_B -3599.779-6235.000j;
voltage_C -3599.779+6235.000j;
object double_assert {
value 7199;
within 2;
target "nominal_voltage";
};
}
This assert test says that nominal_voltage of test_node_1 must equal 7199 +/- 2 (or be within the range of 7197-7201). Since nominal_voltage is 7200, this test would pass. When an assert passes, it will appear nothing happens (unless verbose is set to true). However, when an assert fails, the system will throw an error message and end the simulation. This error throw is what allows the autotest script to know that the test failed and collect the needed information. To actually see what the error was and how far apart the values were, verbose needs to be set to true (#set verbose=1).
Additionally, other operating modes may be used:
- status - This allows the user to set whether the assert should test for a true or false value.
- ASSERT_TRUE (default) - This test will pass if the value given is within the specified range of the target property.
- ASSERT_FALSE - This test will pass if the value given is outside of the specified range of the target property.
- ASSERT_NONE - This will disengage the assert test and pass every value given. This is useful when fed in via a tape player (e.g. ASSERT_NONE may be played in via a tape player, except at given times where it is switched to ASSERT_TRUE. The test will then only pass/fail when ASSERT_TRUE is used.)
- once (not used with enum_assert) - This allows the user to specify that a test be run only once during a simulation. Used in conjunction with in.
- ONCE_FALSE (default) - In this mode, the assert value will be tested continuously at all times during the simulation.
- ONCE_TRUE - When used, this tells the assert to only test the given value against the target value at the time specified by in.
- in - Specifies the time at which a test is to be performed. Uses standard GridLAB-D time formats with single quotes around it (e.g. '2001-01-02 00:00:00 CST').
Double Assert
TODO:
Complex Assert
complex_assert has the ability to look at only the real value, the imaginary, the magnitude, or the angle:
- operation - Allows the user to look at various aspects of the complex number.
- FULL (default) - This compares both the real and imaginary portion of the complex value. within will be applied to both components ( real(target) must be within xx of real(value) and same applies to the imaginary portion).
- REAL - Only compares the real portion of value to be within xx of target. value is still specified as a complex number.
- IMAGINARY - Only compares the imaginary portion of value to be within xx of target.
- MAGNITUDE - Compares the magnitude of value to be within xx of target.
- ANGLE - Compares the angle of value to be within xx of target (must be specified in radians).
For example:
object node {
name test_node_1;
phases ABCN;
nominal_voltage 7200;
voltage_A +7199.558+0.000j;
voltage_B -3599.779-6235.000j;
voltage_C -3599.779+6235.000j;
object complex_assert {
value -2600-7000j;
within 2;
target "voltage_B";
operation MAGNITUDE;
status ASSERT_FALSE;
once ONCE_TRUE;
in '2001-01-02 00:00:00 CST';
};
}
Enumeration Assert
TODO: