Validation

Model users and model developers are usually distinct persons. Therefore, users may not be aware of model limitations. Moreover, only a few model parameters may be meaningful to them.

To address these issues, CoSApp allows model developers to specify the validity range and visibility scope of all variables. This section focuses on the validation feature.

The concept

A validity range and a limit range can be defined on all variables in CoSApp.

The validity range defines an interval within which the model can be used with confidence. The yellow areas between validity range and limits define values for which validation by an expert is required. Finally, values beyond the limits should be avoided as the reliability of the model is unknown.

These ranges are only provided as information, and are not enforced during the execution of a model. Therefore, validation should be performed a posteriori. This behavior has been chosen to limit the constraints on mathematical systems within a model.

Defining validation criteria

CoSApp variables are defined in Port or in System instances. Validity ranges can be specified in the setup of these classes.

For example in a Port:

from cosapp.base import System, Port
from cosapp.drivers import ValidityCheck

class MyPort(Port):

    def setup(self):
        self.add_variable('v', 22.,
            valid_range = (-2, 5),
            invalid_comment = 'design rule abc forbids "a" outside [-2, 5]',
            limits = (-10, None),
            out_of_limits_comment = 'The model has not been tested outside [-10, [',
        )

And in a System:

class MySystem(System):

    def setup(self):
        # Definition of validation criteria on a inward variable 'd'
        self.add_inward('d', 7.,
            valid_range = (-2, 5),
            invalid_comment = "design rule abc forbid 'd' outside [-2, 5]",
            limits = (None, 10),
            out_of_limits_comment = "The model has not been tested outside ]-inf, 10]",
        )

        # Overwrite the default validation criteria on the variable 'v' of port 'port_in'
        port_in = self.add_input(MyPort, 'port_in', {
            'v': dict(  # Variable name in MyPort
                valid_range = (0, 3),
                invalid_comment = "design rule blah-blah recommends 'v' be within [0, 3]",
                limits = (None, 10),
                out_of_limits_comment = "The model has not been tested outside ]-inf, 10]"
            )
        })

If no range are provided, the variable is always considered as valid. In case the value is not valid but falls within the limits, the invalid_comment will be shown to inform the user on the reason behind the validity range. If the value is out of limits, the out_of_limits_comment will be displayed.

If one end of the range is unbounded, users may specify a None value. For example, a non-negative variable will correspond to limits = (0, None).

Displaying validation criteria

You can get relevant information by displaying the documentation of the Port or System object.

from cosapp.tools import display_doc

display_doc(MyPort)

Class: MyPort

Variables

v: 22; ⦗ -10 ⟝ -2 ⟝ value ⟞ 5

display_doc(MySystem)

Class: MySystem

Inputs

• inwards: ExtensiblePort

d 🔒🔒 : 7; -2 ⟝ value ⟞ 5 ⟞ 10 ⦘

• port_in: MyPort

v: 22; 0 ⟝ value ⟞ 3 ⟞ 10 ⦘