Future Infrastructure API Reference

Quick reference for the future infrastructure APIs added to NeqSim.

ProcessSystem Convenience Methods

New methods added directly to ProcessSystem for easy access:

State Management

// Export current state
ProcessSystemState state = process.exportState();

// Save state to file
process.exportStateToFile("checkpoint.json");

// Load and apply state from file
process.loadStateFromFile("checkpoint.json");

Emissions Tracking

// Calculate emissions with default grid factor (0.4 kg CO2/kWh)
EmissionsReport report = process.getEmissions();

// Calculate emissions with custom grid factor
EmissionsReport norwayReport = process.getEmissions(0.05);

// Get total CO2 emissions directly (kg/hr)
double totalCO2 = process.getTotalCO2Emissions();

Safety Scenarios

// Generate single-failure scenarios
List<ProcessSafetyScenario> scenarios = process.generateSafetyScenarios();

// Generate combination scenarios (up to n simultaneous failures)
List<ProcessSafetyScenario> combinations = process.generateCombinationScenarios(2);

Batch Studies

// Create batch study builder
BatchStudy.Builder builder = process.createBatchStudy();

---

ProcessSystemState

State snapshot for checkpointing and version control.

Factory Method

ProcessSystemState state = ProcessSystemState.fromProcessSystem(process);

Configuration

state.setVersion("1.2.3");
state.setDescription("Post-tuning checkpoint");
state.setCreatedBy("engineer@company.com");

Persistence

// Save to file
state.saveToFile("model_v1.2.3.json");

// Load from file
ProcessSystemState loaded = ProcessSystemState.loadFromFile("model_v1.2.3.json");

// Validate integrity
boolean valid = loaded.validateIntegrity();

Accessors

String version = state.getVersion();
String name = state.getProcessName();
Instant timestamp = state.getTimestamp();
String json = state.toJson();

Application

// Create new ProcessSystem from state
ProcessSystem restored = state.toProcessSystem();

// Apply state to existing ProcessSystem
state.applyTo(existingProcess);

---

ModelMetadata

Lifecycle and calibration tracking.

Lifecycle Phases

public enum LifecyclePhase {
    CONCEPT,        // Early screening
    DESIGN,         // Detailed engineering
    COMMISSIONING,  // Construction/startup
    OPERATION,      // Live digital twin
    LATE_LIFE,      // Decommissioning
    ARCHIVED        // No longer active
}

Calibration Status

public enum CalibrationStatus {
    UNCALIBRATED,
    CALIBRATED,
    IN_PROGRESS,
    FRESHLY_CALIBRATED,
    NEEDS_RECALIBRATION
}

Usage

ModelMetadata metadata = new ModelMetadata();
metadata.setAssetId("PLATFORM-A");
metadata.setAssetName("Gas Processing Platform A");
metadata.setLifecyclePhase(LifecyclePhase.OPERATION);
metadata.setResponsibleEngineer("jane.doe@company.com");

// Record validation
metadata.recordValidation("Matched well test", "TEST-001");

// Record modification
metadata.recordModification("Updated compressor curves");

// Update calibration
metadata.updateCalibration(CalibrationStatus.FRESHLY_CALIBRATED, 0.02);

// Check revalidation need
boolean needsRevalidation = metadata.needsRevalidation(90); // days

---

EmissionsTracker

CO2 equivalent emissions tracking.

Constructor

EmissionsTracker tracker = new EmissionsTracker(process);

Configuration

tracker.setGridEmissionFactor(0.05);  // kg CO2/kWh (Norway)

Calculation

EmissionsReport report = tracker.calculateEmissions();

Emission Categories

Category	Description
COMPRESSION	Power consumed by compressors
EXPANSION	Power generated by expanders (negative)
PUMPING	Power consumed by pumps
HEATING	Power consumed by electric heaters
COOLING	Power consumed by coolers
FLARING	Direct CO2 from flaring
VENTING	Direct methane/CO2 emissions

EmissionsReport Methods

// Total emissions
double kgPerHr = report.getTotalCO2e("kg/hr");
double tonPerYr = report.getTotalCO2e("ton/yr");

// Power consumption
double kW = report.getTotalPower("kW");
double MW = report.getTotalPower("MW");

// Export
report.exportToCSV("emissions.csv");
report.exportToJSON("emissions.json");
String json = report.toJson();  // Get as JSON string
String summary = report.getSummary();

---

PredictionResult

Look-ahead prediction output.

Constructor

PredictionResult result = new PredictionResult(
    Duration.ofHours(2),  // horizon
    "Base Case"           // scenario name
);

Adding Predictions

result.addPredictedValue(
    "separator.pressure",
    new PredictedValue(52.5, 2.1, "bara")  // mean, stddev, unit
);

PredictedValue Constructors

// With standard deviation
PredictedValue value = new PredictedValue(50.0, 2.5, "bara");

// With explicit bounds
PredictedValue value = new PredictedValue(50.0, 45.0, 55.0, "bara", 0.95);

// Deterministic
PredictedValue value = PredictedValue.deterministic(50.0, "bara");

Violation Handling

// Add violation
result.addViolation(new ConstraintViolation(...));

// Check for violations
if (result.hasViolations()) {
    String summary = result.getViolationSummary();
    String advice = result.getAdvisoryRecommendation();
}

Status

public enum PredictionStatus {
    SUCCESS,
    WARNING,
    FAILED,
    DATA_QUALITY_ISSUE
}

result.setStatus(PredictionStatus.SUCCESS);

---

SurrogateModelRegistry

ML model management.

Singleton Access

SurrogateModelRegistry registry = SurrogateModelRegistry.getInstance();

Registration

registry.register("flash-model", surrogateModel);
registry.register("flash-model", surrogateModel, metadata);

Prediction

predictWithFallback rejects malformed inputs before either callback, validates finite nonempty results from both paths, and enforces the model’s optional input/output dimensions. A failed surrogate or valid out-of-range request uses physics only when fallback is enabled. See the ML validation and fallback contract for schema, counter and error semantics. Direct calls to predict bypass these registry checks. Numeric/range checks alone do not prove thermodynamic validity.

// Direct prediction
double[] result = registry.get("flash-model").orElseThrow().predict(input);

// With automatic fallback
double[] result = registry.predictWithFallback(
    "flash-model",
    input,
    this::physicsCalculation
);

Management

registry.saveModel("flash-model", "models/flash.ser");
registry.loadModel("flash-model", "models/flash.ser");
Optional<SurrogateMetadata> meta = registry.getMetadata("flash-model");

---

PhysicsConstraintValidator

AI action validation.

Constructor

PhysicsConstraintValidator validator = new PhysicsConstraintValidator(process);

Adding Limits

validator.addPressureLimit("separator", 10.0, 80.0, "bara");
validator.addTemperatureLimit("heater-outlet", 0.0, 300.0, "C");
validator.addFlowLimit("feed", 0.0, 1000.0, "kg/hr");

Configuration

validator.setMassBalanceTolerance(0.01);   // 1%
validator.setEnergyBalanceTolerance(0.05); // 5%
validator.setEnforceMassBalance(true);
validator.setEnforceEnergyBalance(true);

Validation

Map<String, Double> proposedAction = new HashMap<>();
proposedAction.put("heater.duty", 5000000.0);

ValidationResult result = validator.validate(proposedAction);

if (result.isValid()) {
    // Safe to apply
} else {
    String reason = result.getRejectionReason();
    List<ConstraintViolation> violations = result.getViolations();
}

// Validate current state
ValidationResult currentState = validator.validateCurrentState();

---

AutomaticScenarioGenerator

Safety scenario generation and execution.

Constructor

AutomaticScenarioGenerator generator = new AutomaticScenarioGenerator(process);

Failure Mode Configuration

// Add specific modes
generator.addFailureModes(
    FailureMode.COOLING_LOSS,
    FailureMode.VALVE_STUCK_CLOSED
);

// Or enable all
generator.enableAllFailureModes();

Generation

// Single failures
List<ProcessSafetyScenario> single = generator.generateSingleFailures();

// Combinations
List<ProcessSafetyScenario> combos = generator.generateCombinations(2);

Scenario Execution

// Run all single-failure scenarios
List<ScenarioRunResult> results = generator.runAllSingleFailures();

// Run specific scenarios
List<ScenarioRunResult> results = generator.runScenarios(scenarios);

// Get execution summary
String summary = generator.summarizeResults(results);

ScenarioRunResult

ScenarioRunResult result = results.get(0);
boolean success = result.isSuccessful();
String error = result.getErrorMessage();
Map<String, Double> values = result.getResultValues();
long timeMs = result.getExecutionTimeMs();

Analysis

List<EquipmentFailure> failures = generator.getIdentifiedFailures();
String summary = generator.getFailureModeSummary();

---

BatchStudy

Parallel parameter studies.

Builder Pattern

BatchStudy study = BatchStudy.builder(baseCase)
    .name("ParameterStudy")
    .vary("pressure", 20.0, 80.0, 7)
    .vary("temperature", 50.0, 100.0, 5)
    .addObjective("power", Objective.MINIMIZE, p -> getPower(p))
    .addObjective("emissions", Objective.MINIMIZE, p -> getEmissions(p))
    .parallelism(8)
    .stopOnFailure(false)
    .build();

Supported Parameter Paths

Property	Equipment Types
duty	Heater, Cooler
outletPressure	Valve, Compressor, Pump
outletTemperature	Heater, Cooler
percentValveOpening, cv	Valve
polytropicEfficiency, isentropicEfficiency	Compressor
temperature, flowRate	Stream
internalDiameter	Separator

Execution

BatchStudyResult result = study.run();

Result Analysis

int total = result.getTotalCases();
int completed = result.getCompletedCases();
int failed = result.getFailedCases();
Duration runtime = result.getTotalRuntime();

CaseResult best = result.getBestCase("power");
List<CaseResult> successful = result.getSuccessfulCases();

// Export results
result.exportToCSV("results.csv");
result.exportToJSON("results.json");
String json = result.toJson();

// Pareto front analysis
List<CaseResult> pareto = result.getParetoFront("power", "emissions");

---

Package Summary

Package	Classes	Purpose
lifecycle	ProcessSystemState, ModelMetadata	State management, versioning
sustainability	EmissionsTracker, EmissionsReport	CO2e tracking
advisory	PredictionResult, PredictedValue	Look-ahead predictions
ml.surrogate	SurrogateModelRegistry, PhysicsConstraintValidator	ML integration
safety.scenario	AutomaticScenarioGenerator	Safety scenario generation
util.optimization	BatchStudy, BatchStudyResult	Parallel studies