DWIS.ExplainabilityDisplay.Model 0.0.3

Model

The Model project is the shared contract library for the ExplainabilityDisplay solution.

It defines:

• strongly typed data contracts exchanged between workers and OPC UA,
• Blackboard query-bound signal contracts,
• semantic wrappers for profile data,
• and shared configuration used by the WebApp and RealTimeDataSource worker.

This project targets net8.0 and is referenced by all source services and the WebApp.

Purpose in the solution

Model is the single source of truth for:

• OPC UA exposed variables ([OPCUANode(...)] mapped properties),
• semantic metadata and query specifications used by DWIS infrastructure,
• common helper types for time/depth/profile payloads,
• runtime configuration contracts (ConfigurationForWebApp).

Without this project, each service would need to duplicate both the data schema and DWIS metadata conventions.

Core dependencies

The project depends on:

• DWIS.RigOS.Common.Worker

And uses types from:

• DWIS.API.DTO
• DWIS.RigOS.Common.Model
• OSDC.DotnetLibraries.Drilling.DrillingProperties
• DWIS.Vocabulary.Schemas (for semantic facts in LiveSignals)

File-by-file overview

RealTimeData.cs

Defines time-series contracts for real-time logs, including:

• TimeStampedValuePair (DateTime TimeStamp, double Value)
• TimeStampedProfileProperty (List<TimeStampedValuePair>)
• RealTimeData : DWISDataWithOPCUA

RealTimeData contains many OPC UA-mapped curves, typically in triplets/families:

• past and future curves (PastX, FutureX)
• optional min/max envelopes for relevant signals (PastXMin, PastXMax, etc.)

This is the primary publish model used by RealTimeDataSource.

LiveSignals.cs

Defines Blackboard-readable live scalar signals:

• BottomOfStringDepth, BottomHoleDepth
• FlowrateIn, FlowrateOut
• ActiveVolume, BlockPosition
• AnnulusPressure, StandPipePressure
• SurfaceRateOfPenetration, HookLoad
• RotatingDriveSystemTorque, RotatingDriveSystemRotationalSpeed
• SurfaceWeightOnBit

LiveSignals : DWISData is decorated with semantic attributes (SemanticFact, OptionalFact, AccessToVariable, etc.) that build SPARQL query bindings and semantic meaning for variable discovery.

This is the primary read model used by RealTimeDataSource when reading from Blackboard.

AlongStringProfiles.cs

Defines depth-indexed profiles:

• DepthValuePair (Depth, Value)
• DepthProfileProperty (List<DepthValuePair>)
• AlongStringProfiles : DWISDataWithOPCUA

Includes profiles such as:

• axial/rotational speed,
• inclination/azimuth/curvature,
• cuttings and cuttings bed,
• ECD/pore/collapse/fracture pressure gradients.

Used by DepthProfileSource.

ProcedureDescriptionData.cs

Defines procedure template data over relative time:

• ProcedureChoice enum
• TimeValuePair (Duration, Value)
• TimeProfileProperty (List<TimeValuePair>)
• ProcedureDescriptionData : DWISDataWithOPCUA

Contains many OPC UA-mapped profiles for operational procedure phases (off-slips, pump start/stop, top-drive start/stop, mitigation sequences, etc.).

Used by ProcedureDescriptionSource.

DynamicPlanData.cs

Defines stand-level planning and warnings:

• Severity enum
• Annotation class
• StandAnnotationProperty
• DynamicPlanData : DWISDataWithOPCUA

Contains:

• scalar planning values (EstimatedDurationToTD, StandLength, StandCountLeft)
• annotation collections (StandProcedures, StandWarnings)

Used by DynamicPlanSource.

DecisionData.cs

Defines decision/recommendation outputs:

• operational recommendations (PaceReduction, EarlyReciprocation, etc.)
• current/predicted friction indicators
• related standard deviations
• BottomHoleDistance

All mapped with [OPCUANode(...)] inside DecisionData : DWISDataWithOPCUA.

Used by DecisionMakingSource.

ConfigurationForWebApp.cs

Defines shared runtime configuration contract:

• inherits ConfigurationForOPCUA
• includes plot color settings and friction management thresholds
• includes plotting/time-window settings
• includes real-time series persistence/retention settings

Important properties include:

• LeftDepthLogsRecentPast
• RealTimeSeriesObsolescence
• RealTimeSnapshotInterval

Also contains:

• Initialize(...) for configuration bootstrap from IConfiguration
• helper parsers (ReadConfigDouble/Int/TimeSpan/String)
• color class load/save to plotcolorsettings.json

Used by:

• WebApp for UI-related runtime settings
• RealTimeDataSource for retention and backup cadence behavior

Common design pattern in model classes

Most publishable models follow this pattern:

1. Inherit DWISDataWithOPCUA (or DWISData for query-only types).
2. Define lazy metadata dictionaries:
   • OPCUANodes
   • SparQLQueries
   • Manifests
3. Decorate public properties with [OPCUANode(...)] (for publisher contracts) or semantic/query attributes (for Blackboard contracts).

This lets DWIS worker base classes handle manifest registration, query binding, and node publishing using reflection.

Relationship with other projects

• RealTimeDataSource reads LiveSignals and publishes RealTimeData.
• DepthProfileSource publishes AlongStringProfiles.
• DynamicPlanSource publishes DynamicPlanData.
• DecisionMakingSource publishes DecisionData.
• ProcedureDescriptionSource publishes ProcedureDescriptionData.
• WebApp reads and displays data; it also uses ConfigurationForWebApp.

Extending the model safely

When adding new variables:

1. Add a strongly typed property to the relevant model class.
2. Add [OPCUANode(...)] for publishable variables, or semantic attributes for Blackboard-readable variables.
3. Keep units and naming aligned with existing conventions and manifest naming.
4. Update the corresponding source worker to populate/read the new property.
5. Validate end-to-end by running the source and checking OPC UA/WebApp behavior.

Packaging notes

Model.csproj packs:

• README.md as package readme
• LICENSE as package license file

This means this README doubles as the package-level documentation for consumers of the Model library.