Model Hierarchy
Overview
Conceptually, you can think of Juno Cassandra as operating on three levels, as shown in the figure below. Each of the three levels are described in more detail in the following paragraphs.
In the broader IDM context, the word ‘model’ and also ‘deterioration model’ can refer to many things. Also, there is some overlap between the use of the word ‘model’ and ‘algorithm’. In this documentation, we will try to differentiate specifically between two types or levels of models. These are:
- The Framework model
- The Domain model
When you start a Cassandra session, you need to specify which project you are working on, which domain model you are using, and also provide an input (.csv) and (optionally) a committed treatments file. These details define what is called your ‘Work Bench’. More details about setting up your Work Bench can be found here.
The image below shows the relation between a Domain Model and a Project:
The Project Level
Whenever you run a Cassandra model, you will be operating in the context of a Project. In Juno Cassandra, a project refers to the task of running a deterioration model on a specific infrastructure network and for a specific domain model.
For example, when you run a Cassandra Infrastructure Deterioration Model (IDM) for a specific Road Network called network “Council ABC” then that is a project. If you run a Cassandra IDM for the same council’s Bridge Network, then that will be another project. Typically, each of these projects will require it’s own working folder (you can of course put both under the same parent folder, e.g. called ‘Council ABC’).
It is helpful to understand the Project Context by thinking in terms of folders on your desktop computer. Typically, you will want to use a Cassandra project folder only for files related to Juno Cassandra. If, for example, you have many pre-processing files such as supporting documentation, then we recommend you create a sibling folder under the same parent folder, and keep your non-Cassandra-specific files in there.
For the scenario we explained above, you may have the following folder structure on your desktop:
Note that in the example above, there are two Working Folders - one for the bridge network and another for the road network. Both are called ‘Cassandra’ (we recommend you call your Cassandra working folders ‘Cassandra’ so that you can easily identify the folder where your modelling files reside).
To run Juno Cassandra using the Desktop Application, you always need to specify the working folder location. So for the Road Network project for ‘Council ABC’ shown above, if we presume that the folder ‘aa_modelling_projects’ is stored directly on my hard drive ‘c:\’ then the path to my working folder for the Bridge Model will be:
‘C:\zz_modelling_projects\Council_ABC\road_network\Cassandra’
Details about the required structure for your working folder is discussed later sections of this documentation.
The Domain Model
In the context of Infrastructure Deterioration Models (IDM), a domain model is a model that pertains to a specific type of infrastructure. Example of domain-specific models include:
- Bridge Management System models.
- Road Network models.
- Water Network models.
- Rail Network models.
A domain model will normally be designed, tested and calibrated by engineers familiar with the specific domain. For example, a road network model will be coded and managed by engineers with experience in road networks, while a water network model will be designed and managed by engineers with a background in water/pipe systems.
In Juno Cassandra, a user can design and build their own Domain Model using their domain knowledge. Typically, such models will include features to allow for the specific policies and preferences of a specific client or network.
Within a Domain Model, you will typically find sub-models that define aspects such as how fast elements will deteriorate, what the impact of certain treatments are etc. Examples of domain sub-models include the World Bank HDM models for road rutting and roughness development etc. (Paterson 1987).
In Juno Cassandra you have complete freedom to implement the domain sub-models of your choosing. Your domain sub-models can range from traditional regression equations or lookup tables right to Machine Learning models using Random Forests for making more accurate predictions.
Although you can design your domain model in any way you want, for a domain model to link to Juno Cassandra’s Framework Model, the model should implement a specific coupling interface. There are several ways to create such an interface (discussed in the sections below).
The key requirements of a Domain Model interface is that it needs instructions or functions to direct each of the following five model stages:
- Initialisation.
- Triggering treatment strategies;
- Triggering Routine Maintenance where needed (if no treatment selected);
- Resetting condition when a treatment or maintenance has been applied; and
- Incrementing/deteriorating condition if a treatment had not been applied.
More information about these stages can be found at this page.
The Framework Model
The Cassandra Framework Model, which we will refer to as the ‘framework model’, refers to the algorithmic engine that executes a certain procedure over all modelling periods. The framework model refers to compiled software provided by Lonrix Ltd.
The framework model is responsible for structuring and executing the looping over all model elements, detecting when to apply treatments (resets) and when to increment condition (deteriorate), when to trigger and apply routine maintenance and so forth.
The framework model is domain agnostic whereas the domain model, as the name implies, is specific to an engineering domain such as road networks, bridge networks etc. For a more detailed discussion of the elements of the Framework Model, please see this link.
Linking Framework and Domain Models
When you define and code your Domain Model, you are essentially customising the Juno Cassandra framework to do things the way you want it to be done. There are two techniques or levels with which to build a domain model in Juno Cassandra:
You can create a sequential set of functions, called JFunctions, that describe the logic of your domain model. These functions are described in plain text in a table (typically defined in Excel) from where they are then imported and stored in a database so that your Domain Model can be used by others to whom you grant permission. If you are using this approach, you are using the ‘Default Domain Model’.
You can code a .NET Core C# class to hold the logic that describes your domain model. In this case you are using a ‘Custom Domain Model’.
You can also use a combination of these two techniques in which some of your domain model logic is contained in compiled C# code and others are in the JFunctions definition table.
Default Domain Model
In this approach, your Domain Model is defined entirely through the use of JFunctions. For the majority of domain models that do not use Machine Learning models, this approach is the easiest to implement. Using this approach, engineers or modellers with no knowledge of .NET programming can still construct complex domain models provided they have mastered the syntax for expressing their domain model using JFunctions.
In this approach the .NET component of your domain model used is a default C# class provided by Lonrix. This class contains no domain logic and simply helps to load and execute the JFunctions defined in your domain model setup table. The figure below shows how the default .NET domain model class serves to link your Model Setup with the framework model.
Custom Domain Model
This approach requires intermediate level experience in programming .NET C# using Visual Studio. In this approach you code the classes needed to interface with the Cassandra Framework model. You then compile your code as a .dll file and point Cassandra to this .dll in the Meta-setup file. Lonrix can provide an example stub class to show you an example implementation.
This approach is the only approach that currently allows you to use ML.NET machine learning models in your domain model. The figure below conceptually shows how the framework model and the domain model is linked in this approach. Note that in this approach you can still specify JFunctions and therefore a Domain Model setup table is still needed, even though it will mainly be empty.
