Skip to content

[Campaign] State-of-the-art NeqSim MCP process simulation and troubleshooting #3153

Description

@EvenSol

Goal

Make the NeqSim MCP server a state-of-the-art, governed oil-and-gas process-engineering tool that can:

  • translate a short engineering request, equipment list, facility narrative, structured data, or supported PFD/P&ID/DEXPI description into a reviewable NeqSim simulation;
  • grow the same canonical model from one calculation or unit operation into a large, multi-area facility with recycles, controls, constraints, and reusable model state;
  • execute the calculations routinely needed by process, flow-assurance, production-technology, operating-support, and troubleshooting engineers;
  • investigate operational symptoms through explicit hypotheses, simulations, sensitivity cases, and evidence rather than unsupported diagnosis;
  • return concise operator-facing conclusions while retaining detailed balances, assumptions, provenance, convergence evidence, validation findings, and selectively retrievable large-model results.

The server is an advisory engineering calculation layer. It must not autonomously control a plant, write to operational systems, claim accountable engineering approval, or hide missing data and model limitations.

Current baseline to reuse

Do not rebuild capabilities already present on current master.

Engineering and product principles

  1. One canonical model. Use normal NeqSim fluids, streams, ProcessSystem, ProcessModel, topology, design, and result objects. Do not create a second incompatible MCP-only simulator.
  2. Progressive construction. A one-off PVT or equipment calculation must be reusable as an input to a stream, process area, facility, study, and report.
  3. Explicit units and bases. Distinguish standard/actual, mass/molar/volume flow, absolute/gauge pressure, wet/dry basis, and operating/design conditions.
  4. No silent invention. Facility parsing must return mapped facts, assumptions, ambiguities, missing data, unsupported items, and questions. Inferred values require provenance and confidence.
  5. Evidence before diagnosis. Troubleshooting must separate observations, hypotheses, model tests, findings, uncertainty, and recommended next measurements/actions.
  6. Fail visibly. Non-convergence, extrapolation, inconsistent measurements, unit errors, ambiguous topology, invalid thermodynamic choices, or unavailable validation evidence must produce structured diagnostics.
  7. Bounded operation. Preserve time, memory, concurrency, payload, and security limits; make cancellation and partial-result behavior explicit.
  8. Layered results. Return an operator-sized summary first and permit deterministic retrieval of area, equipment, stream, profile, balance, diagnostic, and provenance detail.
  9. Validation maturity is explicit. Runtime availability is not proof of engineering validation. Every result must carry model choice, applicability, benchmark status, and limitations.
  10. Backward compatibility. Evolve stable contracts deliberately, with schemas, migration guidance, and contract tests.

Roadmap

Phase 0 — Current-master audit and acceptance matrix

  • Inventory every MCP tool, resource, prompt, schema, runner, supported equipment type, report path, deployment profile, test, guide, and known limitation on current master.
  • Reconcile open/merged/closed MCP work and prove what Fix MCP security lockout and propagate caller identity #2874, Add MCP model handles, response limits and execution bounds #2875, and Add reusable MCP capability and process execution #3152 deliver on current master.
  • Establish public synthetic acceptance fixtures at four scales: a single calculation/unit, a small train, a multi-area facility, and a large facility with recycles.
  • Create a traceability matrix from each campaign criterion to source, tests, documentation, benchmark evidence, or a confirmed gap.
  • Record baseline runtime, memory, response size, tool-call count, convergence, balance closure, and report usefulness.
  • Define a machine-readable capability/maturity matrix by engineering discipline.

Phase 1 — Facility description to reviewable simulation

  • Define a versioned facility-description contract accepting narrative facts, equipment/stream tables, structured JSON, and supported diagram/DEXPI references without mixing extracted facts with inference.
  • Produce a deterministic normalized specification containing areas, fluids, streams, equipment, connections, operating/design cases, controls, constraints, data provenance, units, confidence, gaps, and questions.
  • Add component/equipment/tag synonym resolution with explicit ambiguity diagnostics.
  • Validate topology, port/phase compatibility, unit consistency, component coverage, boundary conditions, recycle closure, required equipment data, and thermodynamic-model suitability before solving.
  • Generate a canonical ProcessSystem or multi-area ProcessModel plus editable/replayable process definition.
  • Support incremental refinement: add an area, stream, equipment item, case, control, or constraint without rebuilding unrelated solved state.
  • Coordinate diagram ingestion and round-trip semantics with [Campaign] Professional DEXPI and P&ID workflow #2899 rather than implementing a parallel P&ID model.
  • Require an explicit review checkpoint before inferred facility content is treated as an accepted simulation input.

Phase 2 — Small-to-large composable process construction

  • Provide reusable templates/builders for common oil-and-gas building blocks: well/feed, inlet separation, compression, dehydration, gas treatment, NGL recovery, stabilization, produced-water handling, export, injection, utilities, relief/blowdown/flare, and tie-in facilities.
  • Preserve live stream identity, multi-port topology, area boundaries, recycles, adjusters, controllers, design constraints, equipment charts, geometry, and model revisions.
  • Add predictable model composition, cloning, revision, comparison, serialization, Python replay, and selective re-solve behavior.
  • Make unsupported equipment/connections explicit and extensible through reviewed adapters.
  • Prove deterministic build and execution for small, medium, and large multi-area cases.

Phase 3 — Process-engineering calculation coverage

  • Fluids/PVT: fluid characterization, plus fractions, EOS/mixing-rule selection, TP/PH/PS/TV flashes, phase envelopes, dew/bubble points, density/viscosity/thermal properties, standard volumes, calorific value/Wobbe, PVT experiments and regression where validated.
  • Flow assurance: hydrate, water/MEG/TEG, wax, asphaltene, corrosion/scale screening, single- and multiphase pipe/well calculations, profiles, cooldown/transients, erosion and operating envelopes with applicability boundaries.
  • Core equipment: streams, mixers/splitters, separators/scrubbers, valves/chokes, compressors/expanders, pumps, heaters/coolers/heat exchangers, columns/absorbers/strippers, tanks, pipelines/wells, reactors, utilities, and relevant mechanical/design calculations.
  • Facility studies: mass/energy/component balances, equipment performance, capacity/utilization, bottlenecks, operating envelopes, turndown, recycle/control behavior, production allocation/optimization handoff, emissions/energy KPIs, and case comparison.
  • Route eligible generic static calculations through runtime capability discovery only when the exact signature, bounds, maturity, and response contract are known; keep stateful calculations behind curated runners.

Phase 4 — Troubleshooting and operating-support workflow

  • Define a structured troubleshooting case: symptom, time/operating context, observed values, expected behavior, data quality, relevant equipment/topology, hypotheses, tests, findings, confidence, and actions.
  • Convert operator/support-engineer descriptions into testable hypotheses without claiming causality from correlation.
  • Add reusable diagnostic patterns for separation loss, compressor underperformance/surge/recycle, valve restriction, exchanger fouling, column off-spec, hydrate/condensation risk, pipeline pressure loss, recycle non-convergence, instrument inconsistency, and changing feed composition.
  • Compare current/reference/what-if states with conservation, thermodynamic consistency, equipment limits, nearby operating points, and sensitivity/uncertainty evidence.
  • Distinguish process-model mismatch, bad/missing data, equipment degradation, control behavior, and numerical failure.
  • Recommend the next safest measurement, check, or simulation; never issue plant-control commands.
  • Build a public synthetic fault library with known injected causes and measurable pass/fail diagnostic criteria.

Phase 5 — Dynamic, operability, and scenario studies

  • Support bounded steady-state, quasi-steady, and dynamic study orchestration with explicit solver/model selection.
  • Compose startup/shutdown, trip, control-response, depressurization, cooldown, compressor recycle, slugging, and constraint-change cases where the underlying NeqSim model is validated.
  • Coordinate underlying dynamic-model implementation with [Campaign] Professional reservoir-to-market dynamic process simulation #2911 and pipeline/flash campaigns rather than duplicating solver work.
  • Preserve initial state, case definitions, time series, convergence, event chronology, safeguards, limitations, and reproducible replay.
  • Keep all outputs advisory and clearly separate screening from qualified dynamic studies.

Phase 6 — Large-process execution and lifecycle

  • Benchmark representative small (3–5 unit), medium (25–50 unit), large (150+ unit), and stress-scale facility models where feasible.
  • Improve registration, revision, dependency-aware partial solving, warm-state reuse, caching, immutable snapshots, concurrency isolation, cancellation, timeout, recovery, and deterministic replay.
  • Prevent repeated full solves for read-only result retrieval.
  • Stream or page large results by model → area → equipment/stream → property/profile instead of producing context-breaking payloads.
  • Preserve the standard compact response envelope and deterministic selective retrieval after truncation.
  • Record runtime/memory/payload baselines and conservative regression thresholds by environment; do not hide degraded accuracy or convergence to meet a performance target.
  • Add multi-client and tenant-isolation tests for mutable models and long-running studies.

Phase 7 — Engineering results and reporting

  • Define typed, versioned result contracts for fluids, equipment, streams, areas, complete facilities, scenarios, troubleshooting findings, and comparisons.
  • Provide summary/detail levels that retain exact units, basis, case, timestamp/revision, model/provenance, convergence, validation, warnings, and engineering-review requirements.
  • Generate concise operator and support-engineer summaries: what changed, likely mechanisms, evidence, uncertainty, limits, and recommended next action.
  • Generate process-engineering results: stream tables, equipment duties/performance, mass/component/energy balances, constraints/utilization, profiles, case deltas, diagnostics, and assumptions.
  • Support deterministic Markdown/JSON/CSV and suitable visual/report artifacts without making downloadable files the only place results can be reviewed.
  • Validate report completeness, numerical consistency, units, ordering, clipping/size, and selective-detail links for large facilities.

Phase 8 — MCP usability, schemas, and agent cooperation

  • Make discovery task-oriented: “build this facility,” “run this calculation,” “explain this symptom,” and “compare these cases,” not only tool-name discovery.
  • Keep input/output schemas complete, bounded, example-backed, and synchronized with the actual tool surface.
  • Provide fix-oriented validation errors with field paths, accepted units/enums, alternatives, and recoverable next steps.
  • Support resumable multi-step studies and explicit handoffs between facility parsing, model construction, simulation, troubleshooting, validation, and reporting.
  • Add end-to-end protocol tests over STDIO and Streamable HTTP using real MCP clients or a standards-conforming harness.
  • Keep NeqSim agents/skills and MCP contracts synchronized; route domain gaps to the underlying NeqSim capability instead of papering them over in prompts.

Phase 9 — Trust, security, deployment, and observability

  • Preserve profile enforcement, identity, tenant isolation, audit, approval gates, response/execution bounds, OIDC/HTTP security, and advisory-only digital-twin behavior.
  • Add calculation/model/revision correlation IDs, structured timings, cache/solve provenance, and privacy-safe diagnostics.
  • Test malformed, adversarial, oversized, recursive, unsupported, and resource-exhausting inputs.
  • Maintain deployment recipes and health/readiness evidence for desktop, CI, container, and governed team/enterprise use.
  • Prove that secrets, credentials, proprietary input data, and raw plant data are not leaked through logs, reports, caches, or cross-tenant handles.

Phase 10 — Executed reference workflows and completion gate

  • Execute and retain outputs for at least: one PVT/flash study, one equipment calculation, one small facility, one large multi-area facility, and several known-cause troubleshooting cases.
  • Demonstrate narrative facility description → normalized specification/gap review → canonical model → execution → validation → operator summary → detailed engineering report → model revision/replay.
  • Demonstrate progressive reuse from a single fluid/equipment calculation into a complete facility.
  • Validate key engineering results against analytical checks, published/public benchmarks, independent models, experimental data, or defensible physical bounds.
  • Complete focused and proportionate broader tests, formatting/static-analysis/documentation gates, exact protocol tests, security tests, and rendered artifact inspection.
  • Publish a final capability/maturity/benchmark/limitation matrix with exact evidence links.
  • Perform an independent current-master audit: no unmet definition-of-done criterion, no active campaign PR, no unresolved critical/high defect, no stale documentation/schema/example claim.

Definition of done

This campaign is complete only when current default-branch evidence demonstrates all of the following:

  • A user can start with a typical oil-and-gas engineering question or facility narrative and obtain a reviewable canonical model with explicit mappings, assumptions, gaps, and questions.
  • The same model can be extended from a single calculation/unit into a multi-area large facility without incompatible representations.
  • Representative PVT, flash, valve, compressor, separator, exchanger, column, pump, pipeline/well, flow-assurance, balance, performance, capacity, and scenario studies execute through documented contracts where NeqSim has validated functionality.
  • Known-cause synthetic troubleshooting cases produce evidence-backed, uncertainty-aware findings and useful next actions without unsafe control advice.
  • Small, medium, and 150+ unit acceptance models are reproducible, bounded, isolated across clients, and usable without repeated unnecessary full solves or oversized responses.
  • Operator summaries and detailed engineering results are consistent, unit-complete, selectively retrievable, reproducible, and explicit about convergence, validation maturity, assumptions, and limitations.
  • Every public tool/resource/prompt/schema is covered by contract tests and current documentation; security, governance, execution, compatibility, and documentation gates pass.
  • The MCP server remains an advisory calculation and decision-support tool; it never claims plant authority or accountable engineering approval.

Campaign coordination and run ledger

  • Maintain at most one active implementation PR for this MCP campaign and no more than ten open autonomous NeqSim implementation PRs overall.
  • Before every run, read this issue and newest comments, current master, repository instructions, current MCP source/docs/tests, related open/recent PRs, reviews/checks, and overlap roadmaps.
  • Search for merged or active functionality before selecting work. Reuse it and never create a competing implementation.
  • Select the largest coherent dependency-ready increment that remains one reviewable concept. Include implementation, tests, validation, documentation, schemas/examples, and agent/skill contract updates when coupled.
  • Never write to master, merge, enable auto-merge, force-push, or mark a draft ready for review.
  • Every productive run must append a ledger comment containing: timestamp; exact base/head; active autonomous PR count; selected roadmap item and stop boundary; files/PR; tests and engineering validation; documentation impact; limitations/blocker; and next dependency.
  • Open or draft PR work remains in progress until merged. Mark roadmap boxes complete only from verified merged default-branch evidence.
  • Notify only for a new/materially updated PR, a changed blocker/decision, first READY TO MERGE classification for an exact head, or final campaign completion. Keep no-op runs silent.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions