TracModel¶

class tracdap.rt.api.TracModel¶

Base class that model components inherit from to be recognised by the platform

The modelling API is designed to be as simple and un-opinionated as possible. Models inherit from TracModel and implement the run_model() method to provide their model logic. run_model() has one parameter, a TracContext object which is supplied to the model at runtime, allowing it to access parameters, inputs and outputs.

Models must also as a minimum implement three methods to define the model schema, define_parameters(), define_inputs() and define_outputs(). The parameters, inputs and outputs that are defined will be available in the context at runtime. The tracdap.rt.api package includes a number of helper functions to implement these methods in a clear and robust way.

While model components can largely do what they like, there are three rules that should be followed to ensure models are deterministic. These are:

No threading

Use TRAC for random number generation

Use TRAC to access the current time

Threading should never be needed in model code, Python only runs one execution thread at a time and TRAC already handles IO masking and model ordering. Both Pandas and PySpark provide compute concurrency. Random numbers and time will be made available in the TracContext API in a future version of TRAC.

Models should also avoid making system calls, or using the Python builtins exec() or eval().

See also

define_attributes()¶

Define attributes that will be associated with the model when it is loaded into the TRAC platform.

Note

This is an experimental API that is not yet stabilised, expect changes in future versions of TRAC

These attributes can be used to index or describe the model, they will be available for metadata searches. Attributes must be primitive (scalar) values that can be expressed in the TRAC type system. Multivalued attributes can be supplied as lists, in which case the attribute type must be given explicitly. Controlled attributes (starting with trac_ or _) are not allowed and will fail validation.

To define attributes in code, always use the define_* functions in the tracdap.rt.api package. This will ensure attributes are defined in the correct format with all the required fields. Attributes that are defined in the wrong format or with required fields missing will result in a model validation failure.

Returns:: A set of attributes that will be applied to the model when it is loaded into the TRAC platform
Return type:: Dict[str, Value]

abstract define_inputs()¶

Define data inputs that will be available to the model at runtime.

Implement this method to define the model’s inputs, every data input that the model uses must be defined. Models may choose to ignore some inputs, it is ok to define inputs that are not always used.

To define model inputs in code, always use the define_* functions in the tracdap.rt.api package. This will ensure inputs are defined in the correct format with all the required fields. Model inputs that are defined in the wrong format or with required fields missing will result in a model validation failure.

Returns:: The full set of inputs that will be available to the model at runtime
Return type:: Dict[str, ModelInputSchema]

abstract define_outputs()¶

Define data outputs that will be produced by the model at runtime.

Implement this method to define the model’s outputs, every data output that the model produces must be defined and every output that is defined must be produced. If a model defines an output which is not produced, a runtime validation error will be raised after the model completes.

To define model outputs in code, always use the define_* functions in the tracdap.rt.api package. This will ensure outputs are defined in the correct format with all the required fields. Model outputs that are defined in the wrong format or with required fields missing will result in a model validation failure.

Returns:: The full set of outputs that will be produced by the model at runtime
Return type:: Dict[str, ModelOutputSchema]

abstract define_parameters()¶

Define parameters that will be available to the model at runtime.

Implement this method to define the model’s parameters, every parameter that the model uses must be defined. Models may choose to ignore some parameters, it is ok to define parameters that are not always used.

To define model parameters in code, always use the define_* functions in the tracdap.rt.api package. This will ensure parameters are defined in the correct format with all the required fields. Parameters that are defined in the wrong format or with required fields missing will result in a model validation failure.

Returns:: The full set of parameters that will be available to the model at
Return type:: Dict[str, ModelParameter]

abstract run_model(ctx)¶

Entry point for running model code.

Implement this method to provide the model logic. A TracContext is provided at runtime, which makes parameters and inputs available and provides a means to save outputs. All the outputs defined in define_outputs() must be saved before this method returns, otherwise a runtime validation error will be raised.

Model code can raise exceptions, either in a controlled way by detecting error conditions and raising errors explicitly, or in an uncontrolled way as a result of bugs in the model code. Exceptions may also originate inside libraries the model code is using. If an exception escapes from run_model() TRAC will mark the model as failed, the job that contains the model will also fail.

Parameters:: ctx (TracContext) – A context use to access model inputs, outputs and parameters and communicate with the TRAC platform