Maintenance Deferral & Run-Until-Repair Decision Framework

[EvenSol]

PR: Maintenance Deferral & Run-Until-Repair Decision Framework

Summary

Adds a new neqsim.process.maintenance package that enables AI agents and
engineers to assess whether scheduled maintenance on process equipment can be
safely deferred. The framework wires equipment degradation physics (fouling,
efficiency loss) into the existing simulation engine, then layers health
assessment and a rule-based decision engine on top.

Motivation

Maintenance deferral is a common operational decision in oil & gas facilities.
Operators frequently ask: "Can we delay this compressor overhaul by 30 days
until the next planned shutdown?" Answering this rigorously requires:

1. Modelling how degraded equipment performs (efficiency loss, head reduction)
2. Quantifying the impact on production and safety
3. Defining safe temporary operating limits
4. Coordinating deferrals across multiple equipment to manage cumulative risk

NeqSim already had degradationFactor, foulingFactor, and CompressorWashing
classes, but none of these were connected to the actual simulation calculations.
This PR wires them in and builds the decision-support layer on top.

Changes

Phase 1 — Equipment Degradation Wiring

Compressor.java (modified)

• Applied degradationFactor and foulingFactor across all 6 calculation
  paths in run():
  • Chart-based with solveSpeed: head × degradationFactor × (1 − foulingFactor)
  • Chart-based without solveSpeed: same head reduction
  • Non-chart polytropic (detailed/Schultz/default): temporary efficiency reduction
  • Isentropic path (GERG2008/Leachman/Vega): effective isentropic efficiency
• Added applyWashing(CompressorWashing.WashingMethod) — reduces foulingFactor
  by the method's recovery effectiveness
• Added incrementOperatingHours(double hours, double foulingRatePerHour) —
  increments hours counter and applies linear fouling model
• Added incrementOperatingHours(double hours) — hours-only overload

HeatExchanger.java (modified)

• Added FoulingModel field with getter/setter
• Modified UA calculation in run(): computes effective UA as
  1 / (1/UA_clean + R_fouling) when a fouling model is attached
• Added getEffectiveUA() method

Phase 2 — Health Assessment

EquipmentHealthAssessment.java (new)

• Weighted health index: performance (30%) + age/overhaul (20%) + condition
  indicators (50%)
• Severity classification: NORMAL / WATCH / ALERT / CRITICAL
• Estimated remaining useful life (RUL) via linear extrapolation
• ConditionIndicator inner class for vibration, temperature, etc.

Phase 3 — Decision Engine

MaintenanceDeferralAssessment.java (new)

• 7-rule decision engine:
  1. Critical health veto → EMERGENCY
  2. RUL vs requested deferral → PROCEED or REDUCED_SCOPE
  3. Production loss estimation (quadratic model)
  4. Safety risk veto (threshold-based)
  5. Production loss veto (threshold-based)
  6. Economic cost/benefit analysis
  7. All-pass → DEFER with operating envelope

DeferralDecision.java (new)

• Recommendation enum: DEFER / PROCEED_AS_PLANNED / REDUCED_SCOPE / EMERGENCY
• Risk level: LOW / MEDIUM / HIGH / VERY_HIGH
• Economic fields: benefit USD, risk USD, production loss %, safety score
• Human-readable rationale string

TemporaryOperatingEnvelope.java (new)

• Constraint-based operating limits (min/max per parameter)
• isWithinEnvelope() bounds checking
• Monitoring requirements and escalation criteria

Phase 4 — Plant-Wide Coordination

PlantDeferralCoordinator.java (new)

• Iterates over equipment in a ProcessSystem
• autoAssessCompressors() reads degradation/fouling from live compressor objects
• Enforces cumulative safety risk limit across all equipment
• Enforces maximum simultaneous deferrals (default: 3)
• Revokes riskiest deferrals first when plant limits are exceeded

Documentation

• docs/process/maintenance-deferral-framework.md — Full user guide with
  architecture diagram, code examples, and class reference
• Updated docs/REFERENCE_MANUAL_INDEX.md with new entry

Tests

MaintenanceDeferralTest.java — 15 JUnit 5 tests:

• Compressor degradation increases power consumption
• Compressor fouling affects head
• applyWashing() reduces fouling factor
• incrementOperatingHours() tracks hours and fouling
• Health assessment calculation and severity classification (NORMAL, CRITICAL)
• Deferral decision: critical → EMERGENCY, healthy → DEFER, no data → PROCEED
• Temporary operating envelope bounds checking
• Plant coordinator with manual and auto-assessed compressors
• Condition indicators and JSON serialization

Files Changed

File	Change
src/main/java/neqsim/process/equipment/compressor/Compressor.java	Wire degradation into all run() paths, add washing/hours methods
src/main/java/neqsim/process/equipment/heatexchanger/HeatExchanger.java	Connect FoulingModel to UA calculation
src/main/java/neqsim/process/maintenance/package-info.java	New — package documentation
src/main/java/neqsim/process/maintenance/EquipmentHealthAssessment.java	New — health index, severity, RUL
src/main/java/neqsim/process/maintenance/MaintenanceDeferralAssessment.java	New — 7-rule decision engine
src/main/java/neqsim/process/maintenance/DeferralDecision.java	New — decision output model
src/main/java/neqsim/process/maintenance/TemporaryOperatingEnvelope.java	New — operating constraints
src/main/java/neqsim/process/maintenance/PlantDeferralCoordinator.java	New — plant-wide coordination
src/test/java/neqsim/process/maintenance/MaintenanceDeferralTest.java	New — 15 tests
docs/process/maintenance-deferral-framework.md	New — user documentation
docs/REFERENCE_MANUAL_INDEX.md	Add index entry

Testing

Tests run: 15, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

Java 8 Compatibility

All new code uses Java 8 features only. No var, List.of(), Map.of(),
String.repeat(), or other Java 9+ constructs.

Future Work (not in this PR)

• Phase 5: Scenario simulation — run process at projected degradation to
  predict future performance and production impact
• Integration with dynamic simulation for transient degradation modeling
• Pump and valve degradation wiring (same pattern as compressor)
• Historical trending of health index for predictive maintenance
• Integration with ProcessAutomation for string-addressable health queries