Neqsim Autonomous Investigation

NeqSim Autonomous Investigation Skill

Make agents investigate instead of follow a checklist. Use this skill when a task (PEPR action, root-cause, operational study, digital-twin deviation) does not tell you the symptom, the driver, or which relationships matter. The goal is that the agent discovers the important relationships from the data and the flowsheet on its own, forms competing hypotheses, and tests them — reaching findings that were not spelled out in the task.

When to Use

• A PEPR action or work order describes a problem but not a cause.
• Historian data is available but no one has said "look at tag X vs tag Y".
• A model-vs-plant deviation appears and the responsible variable is unknown.
• Any "why is this happening?" question where spoon-feeding relations is wrong.

Do not use this to replace a known, well-scoped calculation — if the symptom and mechanism are already given, go straight to neqsim-root-cause-analysis or the relevant discipline skill.

The Investigation Loop (mandatory ordering)

Run this loop before fixing a scope. Never assume the task's stated classification is correct — treat it as a hypothesis to challenge.

1. Observe (no assumptions). Pull all available tags, not just the ones the task names. Scan each tag against its own baseline and (when available) STID design envelope for what is abnormal. Discover cross-tag relationships with RelationshipGraph — including lead-lag direction, which distinguishes a driver from a follower.
2. Hypothesize (compete). Generate at least three competing causal hypotheses, always including a "not a real problem / instrument or data artifact" hypothesis. Seed them from the discovered leaders (candidate causes), not from intuition alone.
3. Predict (differentiate). For each hypothesis, state what it implies for other tags/streams. Two hypotheses that predict the same thing cannot be distinguished — find a prediction where they disagree (the discriminating test).
4. Test. Use NeqSim (runProcess/runFlowAssurance/simulation verification via RootCauseAnalyzer) plus historian evidence (EvidenceCollector) to check each prediction.
5. Discriminate & iterate. Keep the hypothesis that best explains the pattern across relationships, not a single number. Loop until one dominates or the data is exhausted; report residual ambiguity honestly.

Report the relationships you discovered, not just the answer. A finding without its supporting lead-lag relationships and discriminating test is not complete.

Unsupervised relationship discovery — RelationshipGraph

RelationshipGraph (in neqsim.process.diagnostics) scans every tag pair in a historian data set with no symptom and no hypothesis supplied, and reports which tags move together and, crucially, which moves first. Lead-lag directionality is the signal an agent uses to pick candidate causes on its own.

Java

import java.util.Map;
import neqsim.process.diagnostics.RelationshipGraph;

RelationshipGraph graph = new RelationshipGraph();
graph.setTimestamps(timestamps);      // optional: enables lag in seconds
graph.setMaxLagSamples(10);           // search +/- 10 samples
graph.setMinAbsCorrelation(0.5);      // only report |r| >= 0.5
List<RelationshipGraph.Relationship> edges = graph.analyze(historianData);
String relationshipReport = graph.toTextReport(edges);

for (RelationshipGraph.Relationship r : edges) {
  // r.getSource() leads r.getTarget() (candidate cause -> candidate effect)
  // r.getDirection(): LEADS or SYNCHRONOUS
  // r.getLagSamples() / r.getLagSeconds(): how far ahead the driver moves
  // r.getCorrelation(): strength & sign at the best lag
}

Python (task notebook / runner)

RelationshipGraph = ns.JClass("neqsim.process.diagnostics.RelationshipGraph")

graph = RelationshipGraph()
graph.setTimestamps(timestamps)     # java double[]; omit if unavailable
graph.setMaxLagSamples(10)
graph.setMinAbsCorrelation(0.5)
edges = graph.analyze(historian_map)  # Map<String, double[]>
for r in edges:
    print(r.getSource(), "->", r.getTarget(),
          "r=", round(r.getCorrelation(), 2),
          "lag_s=", r.getLagSeconds())

Reading the output

• A -> B (r=+0.85, leads by 300 s) — A moves first; A is a candidate cause of B. Prioritise hypotheses about A.
• A <-> B (r=+0.90, synchronous) — tightly coupled with no detectable lag; may share a common driver — look for a third tag that leads both.
• A strong statistical edge that does not follow a physical process path (upstream -> downstream in the flowsheet) is a candidate common-cause or instrument artifact, not a direct cause.

External (non-historian) candidate signals: weather

RelationshipGraph only sees what is in the historian data set you hand it. For outdoor/topside equipment, ambient temperature, wind, or sea state can be a driver that is not tagged anywhere in the plant historian. Before concluding "no cause found" for an anomaly on weather-exposed equipment, pull the historical weather for the site and event window with the community neqsim-weather-data skill (WeatherDataService.get_historical) and add it as an extra column to the data handed to RelationshipGraph.analyze(...), exactly like any other tag. A lead-lag edge from an ambient-temperature or wind-speed series into the anomalous tag is then a discovered candidate cause, to be hypothesised and tested like any other RelationshipGraph finding — not asserted from correlation alone.