neqsim-root-cause-analysis

name	neqsim-root-cause-analysis
version	1.2.0
description	Root cause analysis (RCA) framework for process equipment — Bayesian-inspired diagnosis integrating multi-source reliability data (IOGP/SINTEF, CCPS, IEEE 493, Lees, OREDA) as prior, plant historian evidence (likelihood), and NeqSim simulation verification. USE WHEN: diagnosing compressor trips, high vibration, efficiency loss, separator carryover, heat exchanger fouling, or any operational anomaly. Anchors on neqsim.process.diagnostics classes.
last_verified	2026-07-19
requires	{"java_packages":["neqsim.process.diagnostics","neqsim.process.equipment.failure","neqsim.process.automation"]}

NeqSim Root Cause Analysis Skill

Systematic equipment-level root cause analysis integrating process simulation, multi-source reliability data, plant historian time-series, and STID design conditions.

When to Use

• Equipment trip investigation (compressor, pump, turbine)
• High vibration diagnosis
• Efficiency degradation analysis
• Separator liquid carryover or gas blow-by
• Heat exchanger fouling assessment
• Valve erosion or malfunction
• Any operational anomaly requiring structured root cause identification

Architecture Overview

The RCA framework uses a Bayesian-inspired three-stage methodology:

Prior (Reliability Data) × Likelihood (Historian) × Verification (Simulation) = Confidence

Reliability Data Sources

ReliabilityDataSource loads from multiple public databases automatically:

• IOGP Report 434 / SINTEF — offshore O&G equipment (free)
• CCPS 1989 — process vessels, piping, valves (published handbook)
• IEEE 493-2007 — industrial electrical equipment (purchasable standard)
• Lees' Loss Prevention 2012 — generic process industry rates (textbook)
• SINTEF PDS — safety-instrumented systems (purchasable)
• OREDA — offshore equipment (optional, commercial)

No commercial license is required for the default data.

Core Classes

Class	Purpose
RootCauseAnalyzer	Main orchestrator — takes ProcessSystem + equipment name, runs full analysis
Symptom	Enum of 12 equipment symptoms (TRIP, HIGH_VIBRATION, etc.)
Hypothesis	Candidate root cause with expected signal fingerprints, evidence, prior/likelihood/verification scores
HypothesisGenerator	Generates candidate hypotheses from built-in libraries and reliability-data-adjusted priors per equipment type
EvidenceCollector	Analyzes historian/STID data and attaches only hypothesis-relevant supporting or contradictory evidence
DiagnosisCase	Captures equipment, window, provenance, process-model identity, context, and data quality
SimulationVerifier	Clones process and reports explicit status, KPI coverage, and magnitude-aware comparison
RootCauseReport	Ranked output with JSON and text report generation

Package Location

All classes in neqsim.process.diagnostics.

Quick Start

Java

// 1. Create analyzer with running process and target equipment
RootCauseAnalyzer rca = new RootCauseAnalyzer(processSystem, "Compressor-1");

// 2. Set the observed symptom
rca.setSymptom(Symptom.HIGH_VIBRATION);

// 3. Provide historian data (from tagreader or CSV)
Map<String, double[]> historianData = new HashMap<>();
historianData.put("vibration_mm_s", vibrationTimeSeries);
historianData.put("discharge_temp_C", tempTimeSeries);
historianData.put("power_kW", powerTimeSeries);
rca.setHistorianData(historianData, timestamps);

// 4. Set design limits from STID
rca.setDesignLimit("vibration_mm_s", Double.NaN, 7.1);
rca.setDesignLimit("discharge_temp_C", Double.NaN, 180.0);

// 5. Optionally provide STID design values
Map<String, String> stidData = new HashMap<>();
stidData.put("design_flow_kg_hr", "50000");
stidData.put("design_efficiency_pct", "82");
rca.setStidData(stidData);

// 6. Run analysis
RootCauseReport report = rca.analyze();

// 7. Get results
String textReport = report.toTextReport();
String json = report.toJson();
Hypothesis topCause = report.getTopHypothesis();

Python (Jupyter)

RootCauseAnalyzer = ns.JClass("neqsim.process.diagnostics.RootCauseAnalyzer")
Symptom = ns.JClass("neqsim.process.diagnostics.Symptom")

rca = RootCauseAnalyzer(process, "Compressor-1")
rca.setSymptom(Symptom.HIGH_VIBRATION)

# Convert numpy arrays to Java
from jpype import JArray, JDouble
historian = ns.HashMap()
historian.put("vibration_mm_s", JArray(JDouble)(vibration_data.tolist()))
rca.setHistorianData(historian, JArray(JDouble)(timestamps.tolist()))

report = rca.analyze()
print(str(report.toTextReport()))

Symptom Reference

Symptom	Description	Related Categories
TRIP	Equipment trip/shutdown	MECHANICAL, CONTROL, EXTERNAL
HIGH_VIBRATION	Vibration above limits	MECHANICAL
SEAL_FAILURE	Seal leakage or failure	MECHANICAL
HIGH_TEMPERATURE	Temperature exceeding limits	MECHANICAL, PROCESS
LOW_EFFICIENCY	Performance below design	PROCESS, MECHANICAL
PRESSURE_DEVIATION	Unexpected pressure change	PROCESS, CONTROL
FLOW_DEVIATION	Unexpected flow change	PROCESS, CONTROL
HIGH_POWER	Power consumption above normal	PROCESS, MECHANICAL
SURGE_EVENT	Compressor surge	PROCESS, CONTROL
FOULING	Fouling or deposit buildup	PROCESS
ABNORMAL_NOISE	Unusual noise patterns	MECHANICAL
LIQUID_CARRYOVER	Liquid in gas outlet	PROCESS

Built-in Hypothesis Libraries

Compressor

• HIGH_VIBRATION: Bearing wear, impeller imbalance, shaft misalignment, fouled impeller, loose foundation
• HIGH_TEMPERATURE: Seal degradation, process gas composition change, fouled intercooler, recycle valve malfunction
• LOW_EFFICIENCY: Internal leakage, fouled impeller, eroded impeller, gas composition change
• SURGE_EVENT: Low suction flow, blocked suction, anti-surge valve failure, gas composition change
• TRIP: Bearing failure, high vibration, high discharge temperature, low lube oil pressure, process upset

Pump

• HIGH_VIBRATION: Cavitation, impeller wear, shaft misalignment
• LOW_EFFICIENCY: Impeller wear, internal recirculation
• TRIP: Bearing failure, seal failure, low suction pressure

Separator

• LIQUID_CARRYOVER: Demister fouled, high liquid level, feed rate exceeded, foam formation
• PRESSURE_DEVIATION: Pressure control valve malfunction, blocked outlet, relief valve leaking
• FOULING: Wax deposition, scale buildup, sand accumulation

Heat Exchanger

• HIGH_TEMPERATURE: Fouled tubes, loss of cooling, bypass valve stuck, air in cooling water
• LOW_EFFICIENCY: Fouling, tube leak, flow maldistribution
• PRESSURE_DEVIATION: Tube blockage, shell-side fouling

Valve

• FLOW_DEVIATION: Trim erosion, actuator malfunction, positioner calibration drift
• ABNORMAL_NOISE: Cavitation, flashing, vibration from upstream piping

Evidence Analysis Methods

Evidence is hypothesis-specific. Built-in hypotheses define expected signal fingerprints such as vibration|bearing increasing, lubeOilPressure below limit, demisterDp increasing, or antiSurgeValve not opening. Historian and STID observations are matched by alias pattern. Matching observations become supporting evidence; opposite observations become contradictory evidence; unrelated trends are ignored instead of inflating all hypotheses.

Each evidence item includes:

• supporting: whether the observation supports or contradicts the hypothesis
• weight: the importance of the expected signal in the hypothesis fingerprint
• sourceReference: optional source/tag/document reference for traceability

Trend Analysis

Linear regression on time-series data. Reports slope, R-squared, and percent change.

• STRONG: R-squared > 0.7 and > 10% change
• MODERATE: R-squared > 0.5
• WEAK: R-squared > 0.3

Threshold Exceedance

Checks how many data points exceed design limits.

• STRONG: > 20% of data exceeding limits
• MODERATE: > 5%
• WEAK: 0-5%

Rate-of-Change Detection

Identifies sudden step changes using 3-sigma detection on first differences. Step changes produce STRONG evidence.

Correlation Analysis

Pearson correlation between all parameter pairs. Reports correlations with |r| > 0.7.

• STRONG: |r| > 0.9
• MODERATE: 0.7 < |r| < 0.9

STID Cross-Reference

Compares current (latest) values to STID design values.

• STRONG: > 20% deviation from design
• MODERATE: 10-20% deviation

Simulation Verification

The verifier clones the process system, applies a perturbation matching each hypothesis, runs the modified process, and compares both direction and normalized response magnitude to the historian data pattern where a defensible KPI match exists.

Every likelihood and verification stage has an explicit EvaluationStatus: UNKNOWN, EVALUATED, UNSUPPORTED, or FAILED. Unknown, unsupported, and failed stages are neutral in confidence multiplication. An EVALUATED zero correctly drives the raw hypothesis score to zero. Reports also expose verification coverage and comparison count; do not present low-coverage verification as conclusive.

Perturbation Examples

Hypothesis	Perturbation Applied
Seal degradation	Reduce polytropic efficiency by 20%
Fouled impeller	Reduce polytropic efficiency by 15%
Surge condition	Reduce polytropic efficiency by 30%
Heat exchanger fouling	Increase outlet temperature by 10°C
Loss of cooling	Set outlet = inlet temperature

Verification Score

The score (0-1) combines direction and the ratio of normalized simulated/observed response magnitudes, then qualifies it by comparable-KPI coverage. Opposite directions score zero. No defensible comparison yields UNKNOWN, not an invented midpoint score.

For operational decisions, attach a DiagnosisCase with the historian query/reference, process-model ID and revision, operating mode, and known quality qualifications. It is emitted in RootCauseReport.toJson() and MCP JSON.

Integration with Other Skills

Skill	Integration
neqsim-autonomous-investigation	Upstream — when the symptom/driver is NOT given, run the observe→hypothesize→test loop and discover lead-lag relationships (RelationshipGraph) first, then feed the discovered candidate causes into RCA instead of a fixed symptom
neqsim-plant-data	Read historian data via tagreader API
neqsim-stid-retriever	Retrieve STID design documents
neqsim-technical-document-reading	Extract design values from datasheets
neqsim-troubleshooting	Recovery strategies after diagnosis
neqsim-process-safety	Link RCA findings to barrier management
neqsim-pid-process-operations	P&ID context for equipment relationships

When the symptom is unknown, do not ask the user "what should I look for?". Chain neqsim-plant-data → neqsim-autonomous-investigation → this skill: the investigation skill scans all tags for anomalies and lead-lag relationships, and hands the candidate causes here for Bayesian scoring + simulation verification. The one-call path is RootCauseAnalyzer.analyzeAutonomous() (or analyzeAutonomous(tagToEquipment) to also classify relationships against the flowsheet topology) — it infers the symptom with AnomalyScanner, discovers relationships with RelationshipGraph, classifies them with CausalTopologyModel, and adds matched anomaly/topology findings to hypothesis evidence before ranking. Ambiguous, counter-flow, and common-cause edges remain visible but do not silently boost scores.

MCP Tool

Use runRootCauseAnalysis MCP tool for programmatic access:

{
  "tool": "runRootCauseAnalysis",
  "arguments": {
    "processJson": "{ ... NeqSim process JSON ... }",
    "equipmentName": "Compressor-1",
    "symptom": "HIGH_VIBRATION",
    "historianCsv": "timestamp,vibration,temperature\n0,3.5,150\n3600,3.8,152\n...",
    "designLimits": {"vibration": [null, 7.1], "temperature": [null, 180]},
    "simulationEnabled": true,
    "diagnosisCase": {
      "caseId": "trip-2026-07-19"
       
       
        
    
  

Output Format

JSON Report Structure

{
  "equipment": "Compressor-1",
  "equipmentType": "compressor",
  "symptom": "HIGH_VIBRATION",
  "timestamp": "2026-06-15T10:30:00",
  "dataPointsAnalyzed": 2400,
  "parametersAnalyzed": 8,
  "diagnosisCase": {
    "caseId": "trip-2026-07-19",
    "equipmentName": "Compressor-1",
    "processModelId": "export-compression",
    "processModelRevision": "model-rev-7"
  },
  "summary": "Most likely root cause: Bearing wear (72.3% confidence)...",
  "hypotheses": [
    {
      "rank": 1
       
       
       
       
       
       
       
       
       
       
       
       
        
           
           
           
           
           
           
           
        
      
         
    
  

Extending the Framework

Custom Hypothesis Libraries

HypothesisGenerator gen = new HypothesisGenerator();

// Register custom hypotheses for a specific equipment type and symptom
gen.register("compressor", Symptom.HIGH_VIBRATION,
    new Hypothesis.Builder()
        .name("liquid_ingestion")
        .description("Liquid droplets entering compressor causing vibration")
        .category(Hypothesis.Category.PROCESS)
        .priorProbability(0.1)
        .addExpectedSignal("scrubberLevel|separatorLevel|level",
            Hypothesis.ExpectedBehavior.HIGH_LIMIT, 3.0,
            "High upstream scrubber level supports liquid ingestion")
        .addExpectedSignal("vibration|flowInstability", Hypothesis.ExpectedBehavior.STEP_CHANGE,
            2.5, "Liquid ingestion normally creates a sudden vibration/flow disturbance")
        .addAction("Check scrubber level")
        .addAction("Inspect inlet piping for liquid accumulation")
        .build());

RootCauseAnalyzer rca = new RootCauseAnalyzer(process, "Compressor-1");
rca.setHypothesisGenerator(gen);

Loading Evidence from CSV

EvidenceCollector collector = new EvidenceCollector();
collector.loadFromCsv("path/to/historian_export.csv");
// CSV format: timestamp, param1, param2, ...

Integrated Workflow: Tagreader + STID + NeqSim Simulation

The RCA framework is designed to consume data from three sources simultaneously. Below is the canonical workflow combining all three.

Step 1: Retrieve Historian Data via Tagreader

Use the neqsim-plant-data skill to pull time-series from the plant historian (OSIsoft PI or Aspen IP.21) and convert to the CSV format RCA expects.

# Python — pull tagreader data and format for RCA
import pandas as pd

# Tag mapping from STID/P&ID documentation
tag_map = {
    "VT-101.PV": "vibration_mm_s",
    "TT-101.PV": "discharge_temp_C",
    "PT-101.PV": "suction_pressure_bara",
    "FT-101.PV": "mass_flow_kg_hr",
    "JI-101.PV": "power_kW",
}

# Read from historian (tagreader API or CSV export)
df = pd.read_csv("historian_export.csv")
df = df.rename(columns=tag_map)

# Convert to CSV string for RCA input
historian_csv = df.to_csv(index=False)

Step 2: Extract STID Design Data

Use the neqsim-stid-retriever and neqsim-technical-document-reading skills to extract design limits and reference values from STID datasheets.

# STID data extracted from datasheet DS-K-101 rev.C
stid_data = {
    "designFlow_kg_hr": "50000",
    "designEfficiency_pct": "82",
    "designDischargePressure_bara": "45.0",
    "maxVibration_mm_s": "7.1",
    "maxDischargeTemp_C": "180",
    "bearingType": "tilting_pad",
    "lastInspectionDate": "2024-06-15",
    "tagreaderSource": "PI Web API: VT-101, TT-101, PT-101, FT-101, JI-101",
    "sourceReference": "STID DS-K-101 rev.C and PI trend 2025-06-01 to 2025-06-15",
}

Step 3: Build Process Model and Run RCA

import json

RootCauseRunner = ns.JClass("neqsim.mcp.runners.RootCauseRunner")

rca_input = {
    "processJson": json.dumps(process_json),
    "equipmentName": "Compressor-1",
    "symptom": "HIGH_VIBRATION",
    "historianCsv": historian_csv,
    "simulationEnabled": True,
    "designLimits": {
        "vibration_mm_s": [None, 7.1],
        "discharge_temp_C": [None, 180.0],
        "mass_flow_kg_hr": [40000, 60000],
    },
    "stidData": stid_data,
}

result = json.loads(str(RootCauseRunner.run(json.dumps(rca_input))))
print(f"Top cause: {result['hypotheses'][0]['name']} "
      f"({result['hypotheses'][0]['confidence']:.1%})")

Step 4: Trace Evidence Back to Source

Every evidence item in the RCA output carries a sourceReference field linking to the original tagreader tag or STID document. This enables auditable traceability from diagnosis to plant data:

hypothesis.evidence[0].sourceReference → "PI:VT-101.PV trend analysis"
hypothesis.evidence[1].sourceReference → "STID DS-K-101: design vibration limit 7.1 mm/s"

MCP Example Catalog

Three pre-built examples demonstrate the integration:

Example	Equipment	Symptom	Data Sources
compressor-high-vibration	Compressor	HIGH_VIBRATION	PI historian, STID datasheet
separator-liquid-carryover	Separator	LIQUID_CARRYOVER	PI historian (demister dP, level), STID datasheet
hx-fouling	Heat Exchanger	FOULING	IP.21 historian (outlet temp, shell dP), vendor datasheet

Access via MCP: neqsim://examples/root-cause/separator-liquid-carryover

Post-Trip Analysis: Detect → Trace → Restart

After the RCA framework identifies what went wrong, the post-trip analysis classes answer three follow-up questions:

1. What tripped? — TripEventDetector monitors process parameters against thresholds
2. How did the failure propagate? — FailurePropagationTracer traces cascade through topology
3. How do we restart? — RestartSequenceGenerator produces an optimised restart plan

Classes

Class	Package	Purpose
TripEvent	neqsim.process.diagnostics	Immutable data record for a detected trip (equipment, parameter, threshold, actual, severity)
TripEventDetector	neqsim.process.diagnostics	Monitors equipment parameters and fires TripEvent when thresholds are breached; supports high/low trips, deadband, first-trip-only mode
FailurePropagationTracer	neqsim.process.diagnostics	Uses ProcessTopologyAnalyzer + DependencyAnalyzer to BFS-trace how a failure cascades downstream/upstream; produces PropagationResult with PropagationStep list
RestartStep	neqsim.process.diagnostics.restart	Single step in a restart sequence (equipment, action, precondition, delay, priority)
RestartSequenceGenerator	neqsim.process.diagnostics.restart	Generates topologically-ordered restart plans with safety checks, root-cause verification, utility confirmation, equipment-specific ramp-up actions, and system verification

Java Quick Start

// ── Step 1: Detect trip ──
TripEventDetector detector = new TripEventDetector(processSystem);
detector.addTripCondition("Compressor-1", "pressure", 150.0, true,
    TripEvent.Severity.HIGH);
List<TripEvent> trips = detector.check(simulationTime);

// ── Step 2: Trace propagation ──
FailurePropagationTracer tracer = new FailurePropagationTracer(processSystem);
FailurePropagationTracer.PropagationResult propagation = tracer.trace(trips.get(0));
String propagationSummary = propagation.toTextSummary();

// ── Step 3: Generate restart plan ──
RestartSequenceGenerator generator = new RestartSequenceGenerator(processSystem);
generator.setCustomRampUpTime("Compressor-1", 300.0);  // 5 min ramp-up
RestartSequenceGenerator.RestartPlan plan = generator.generate(propagation);
String restartPlanReport = plan.toTextReport();
String json = plan.toJson();

Python (Jupyter)

TripEventDetector = ns.JClass("neqsim.process.diagnostics.TripEventDetector")
TripEvent = ns.JClass("neqsim.process.diagnostics.TripEvent")
FailurePropagationTracer = ns.JClass("neqsim.process.diagnostics.FailurePropagationTracer")
RestartSequenceGenerator = ns.JClass("neqsim.process.diagnostics.restart.RestartSequenceGenerator")

detector = TripEventDetector(process)
detector.addTripCondition("Compressor-1", "pressure", 150.0, True, TripEvent.Severity.HIGH)
trips = detector.check(0.0)

tracer = FailurePropagationTracer(process)
propagation = tracer.trace(trips[0])
print(str(propagation.toTextSummary()))

generator = RestartSequenceGenerator(process)
plan = generator.generate(propagation)
print(str(plan.toTextReport()))

TripEventDetector Features

• High/low trips: addTripCondition(equip, param, threshold, isHigh, severity)
• Deadband: setDeadbandFraction(0.02) — 2% of threshold to avoid chatter
• First-trip-only: setFirstTripOnly(true) — fire once per condition
• Parameter types: "pressure", "temperature", "flowRate" (reads from equipment outlet)
• JSON output: detector.toJson() — lists all detected trips

FailurePropagationTracer Features

• Trace by name: tracer.trace("Compressor-1")
• Trace by trip event: tracer.trace(tripEvent)
• Max cascade depth: tracer.setMaxCascadeDepth(3)
• Impact levels: DIRECT, INDIRECT, POTENTIAL per cascade depth
• Output: PropagationResult with toJson(), toTextSummary()

RestartSequenceGenerator Features

• From propagation: generator.generate(propagationResult)
• From equipment list: generator.generate(Arrays.asList("Comp-1", "Cooler-1"))
• Custom ramp-up: generator.setCustomRampUpTime("Comp-1", 300.0)
• Custom preconditions: generator.setCustomPrecondition("Comp-1", "Verify lube oil pressure > 2 bara")
• Equipment-specific actions: auto-selects restart actions by equipment type (compressor, separator, pump, HX, valve, column, pipe)
• Output: RestartPlan with toJson(), toTextReport()
• Plan structure: Safety check → Root cause verification → Utilities → Equipment (upstream-first) → System verification