Model and ModelProxy¶

Model¶

class simu.Model¶

Bases: ABC

This is the base class for all process models to be implemented.

By deriving from this class, handler objects are available as class attributes to deal with the particular aspects. Visit their documentation for details.

The model implementation is then divided into two parts: (a) the interface, and (b) the model implementation itself. These parts are represented by the two methods interface() and define() respectively.

A model is then either instantiated by a parent model, whereas it is represented in that parent model by a ModelProxy object, or it can be defined as the top level model by calling top().

__init__()¶: The constructor is parameterless but still needs to be called by the subclass constructors (if implemented) to initialise the object. Defining a constructor for the subclasses can be useful to pass custom data into the model.

parameters: ParameterHandler¶: The handler object that takes care of parameter configuration

properties: PropertyHandler¶: The handler object that takes care of property configuration

materials: MaterialHandler¶: The handler object that takes care of materials

hierarchy: HierarchyHandler¶: The handler object that takes care of defining sub models

residuals: ResidualHandler = None¶: The handler object that takes care of residuals

bounds: BoundHandler = None¶: The handler object that takes care of domain boundaries

classmethod top(name: str = 'model') → ModelProxy¶

Define this model as top level model, hence instantiate, create proxy, and finalise it.

This is the recommended and fastest way to declare a model as being the top level model. It will create a proxy object (via proxy()) and finalise the configuration of it via simu.core.model.base.ModelProxy.finalise().

Performing the finalisation in one go after creating the proxy object is only possible, if the model is suitable to be top model. That is, it must not have material ports or parameters to be connected.

Parameters:: name (str) – The name of the top level model
Returns:: The readily configured ModelProxy object

classmethod proxy(name: str = 'model') → ModelProxy¶

Instantiate and create proxy of this model.

This is a helper method called by the HierarchyHandler when defining a child model. After the proxy class is generated, the parent model can connect materials and provide parameters. When that is done, the proxy object can be finalised.

Parameters:: name (str) – The name of the top level model
Returns:: The ModelProxy object, ready for configuration from parent context. It then still needs to be finalised.

interface() → None¶

This virtual method is to define all model parameters, material ports, and properties provided by this model. This makes the interface of the model in the hierarchical context nearly self-documenting. A simple example implementation could be

def interface(self):
    """Here a nice documentation of the model interface"""
    self.parameters.define("length", 10.0, "m")
    self.properties.provide("area", unit="m**2")

Above interface requires a parameter called length with a default value of 10 metres. It promises to calculate a property called area which has a unit compatible to square metres.

abstractmethod define() → None¶

This abstract method is to define the model implementation, including the use of submodules, creation of internal materials, and calculation of residuals and model properties. Matching to the example described in the interface() method, a simple implementation could be

def define(self):
    """Here documentation of the internal function of the model.
    This distinction can be used to include this doc-string only
    for detailed documentation sections."""
    length = self.parameters["length"]
    self.properties["area"] = length * length

Here we read out the previously defined parameter length and calculate the property area.

create_proxy(name: str = 'model') → ModelProxy¶: Create a proxy object for configuration in hierarchy context. This is the instance variant of the proxy() class method.

class property cls_name: str¶

The name of the derived class with module path for hopefully unique identification.

This method is mainly used to uniquely name static parameters of a model.

Returns:: The name of the class with the module path
Return type:: str

ModelProxy¶

class simu.core.model.base.ModelProxy¶

Proxy class for models, being main object to relate to when accessing a child model during definition of the parent model.

As for the Model class, this proxy version offers via its handlers functionality to deal with parameters, properties, hierarchy, materials, and residuals, but the angle of view is different:

The Model class deals with the implementation of the model, while the ModelProxy class offers its access to connect to it as a client. This client is most likely a parent Model or, if it is a top level model, a NumericHandler object.

ModelProxy objects are created from within the Model class, and do not need to be instantiated directly by SiMu client code.

__init__(model: Model, name: str)¶

parameters: ParameterProxy¶: The proxy of the parameter handler, to connect and update parameters

properties: PropertyProxy¶: The proxy of the property handler, making properties available

hierarchy: HierarchyProxy¶: The proxy of the hierarchy handler, to parametrise child models

materials: MaterialProxy¶: The proxy of the material handler, to connect material ports

residuals: Mapping[str, Residual]¶: A handler object that takes care of residuals. This is really just a non-mutable mapping of residuals, as the client code is not supposed to temper with the definition of the child model. The residuals are still browsable, as required for instance by the NumericHandler object for obvious reasons.

bounds: Mapping[str, Quantity]¶: The non-mutable proxy of the bound handler, to be queried by the NumericHandler.

finalise() → Self¶: After the parent model has connected parameters and materials, this method is called to define and finalise itself. The final part of this process is to validate correct configuration and to clean up data structures.

AModel¶

class simu.AModel¶

Bases: Model, ABC

This is a wrapper class of Model to enable short notations for common method calls, and by that allowing to shorten the syntax when creating models, while still keeping the underlying structure.

The abbreviations are given in the following table:

Abbreviation	… resolves to
pa	`parameters`
pad	`parameters.define`
pas	`parameters.static`
pr	`properties`
prd	`properties.declare`
h	`hierarchy`
hd	`hierarchy.declare`
ha	`hierarchy.add`
m	`materials`
md	`materials.define_port`
mcf	`materials.create_flow`
mcs	`materials.create_state`
r	`residuals`
ra	`residuals.add`
b	`bounds`
ba	`bounds.add`

__init__()¶: The constructor is parameterless but still needs to be called by the subclass constructors (if implemented) to initialise the object. Defining a constructor for the subclasses can be useful to pass custom data into the model.

create_proxy(name: str = 'model') → AModelProxy¶: Create a proxy object for configuration in hierarchy context. By redefining Model.create_proxy, instances of AModel also generate AModelProxy objects when being exposed in parent model context.

AModelProxy¶

class simu.core.model.amodel.AModelProxy¶

This is a wrapper class of ModelProxy to enable short notations for common method calls, and by that allowing to shorten the syntax when creating models, while still keeping the underlying structure.

The abbreviations are given in the following table:

Abbreviation	… resolves to
pa	`parameters`
pap	`parameters.provide`
pau	`parameters.update`
pr	`properties`
h	`hierarchy`
m	`materials`
mc	`materials.connect`
mcm	`materials.connect_many`
r	`residuals`
b	`bounds`