Monitoring Diagnostics Toolkit

Equipment-specific monitoring from temperature, pressure, flow, inventory and position sensors. Use independent Python modules to calculate mass and heat balances, hydraulic resistance, membrane permeability, normal-performance residuals and causal alarms. Every diagnostic returns its calculated quantities, validity, decision reasons and provenance alongside its score.

Korean README · User guide · API reference · Model equations

Research alpha. Software verification is separate from measured fault validation. An alarm is neither a fault probability nor a confirmed root cause. The latest weak heat-pump detection gain depends on a 0.3 K condensing-temperature difference between sessions; its specificity to evaporator flow reduction remains unproven.

Equipment modules: purpose, inputs, parameters and outputs

Names below are semantic sensor roles, mapped to actual column names using channels={role: column_name}. A question mark marks an optional sensor. All diagnostics return the common DiagnosticResult described below. Consult the API reference for exact constructor names, defaults and conditional sensor requirements.

Common alarm options are persistence_s, max_gap_s and allowed_modes. An optional operating role, unit 1, restricts decisions to observations equal to 1. Default thresholds are not site qualification. Models requiring a reference must be fitted on caller-confirmed normal data or restored with set_reference.

Conditional sensor paths

Oil feed pressure and net oil differential pressure have different meanings. Acoustic normalization, nominal heat demand, fluid properties and sensor calibration must have an explicit basis; the toolkit does not invent missing measurements.

Additional Python modules

These APIs are available from equipment_diagnostics; they are not automatically registered among the 11 CLI kinds. Training the supervised filter models requires the optional learning dependencies. No corpus-trained model is distributed.

Installation and quick start

python -m pip install monitoring-diagnostics-toolkit
equipment-diagnose list --details

From a source checkout:

python -m pip install -e ".[dev]"
# Install only the optional groups you need:
python -m pip install -e ".[learning,physics,public-data]"

The distribution was renamed for public release. The import namespace, CLI and equipment-diagnostics.* JSON identifiers retain their existing compatibility names. External datasets and related project checkouts are not included in the installation.

Minimal Python example: vaporizer outlet low limit

import numpy as np
from equipment_diagnostics import SensorBatch, VaporizerDiagnostic

batch = SensorBatch(
    time_s=np.arange(5.0),
    values=np.column_stack((np.full(5, 270.0), np.full(5, 0.1))),
    channels=("gas_out_k", "flow"), units=("K", "kg/s"),
    clock_id="logger_elapsed_s", asset_id="vaporizer_01", origin="synthetic",
)
monitor = VaporizerDiagnostic(
    {"outlet_temperature": "gas_out_k", "mass_flow": "flow"},
    shortfall_limit_k=5.0, minimum_outlet_k=280.0,
    prediction_mode="minimum_only", persistence_s=2.0,
)
result = monitor.score(batch)
print(list(result.states))
print(result.to_dict()["summary"])

Complete CSV/JSON example without external data

Run from the source checkout. This deterministic synthetic example connects ten diagnostics; it is not a coupled physical plant or measured validation of all eleven kinds.

python examples/generate_demo.py --output outputs/demo
equipment-diagnose fit --config outputs/demo/config.json --data outputs/demo/normal.csv --output outputs/demo/reference.json
equipment-diagnose run --config outputs/demo/config.json --data outputs/demo/operation.csv --reference outputs/demo/reference.json --output outputs/demo/report.json

fit uses data that the caller has confirmed as normal. Where a Python API exposes calibrate, use a separate normal calibration batch. The CLI neither verifies health automatically nor removes fault observations on the caller's behalf.

Common input and output contract

Unit strings must match exactly: K, Pa, kg/s, m3/s, W, 1/s, 1, etc. Convert Celsius to K, kPa to Pa and rpm to 1/s explicitly. Absolute, gauge and differential pressures are different quantities. Relative humidity is not humidity ratio.

UNKNOWN is not a healthy negative decision. PENDING is valid but has not completed the configured persistence. Report decision coverage alongside accuracy. Do not relabel incompatible clocks, assets or origins merely to make an integration accept them.

Evidence and current applicability

These are recorded development observations, not new validation created by publishing the package. Detailed denominators, partitions, candidates and limitations are in the latest two-target study.

Accuracy=(TP+TN)/(valid labeled samples); recall=TP/(TP+FN); FPR=FP/(FP+TN); decision coverage=(valid decisions)/(declared target observations). Report raw-data coverage separately when startup is excluded. Fault-only subsets have no estimable FPR. Time-series rows are not independent fault events. Delay must name its starting point: the weak-EF delay above starts at the first eligible positive observation after a fixed exclusion, not an independently measured physical onset.

Even with disjoint fitting and calibration rows, redesigning a model after inspecting evaluation outcomes makes the resulting study reused development evaluation. Longer alarm holding and improved raw detection are reported separately.

Verification and related projects

python -m pytest
python -m pytest -o addopts="" -m "not integration"
python scripts/verify_physics.py
python scripts/verify_stages.py

The second command needs the optional physical-verification dependencies. External integration checks require separate, pinned project checkouts. The public release records 286 software/physics tests, seven scoped object integrations and Windows/Linux Python 3.11/3.12 CI. Passing tests do not establish universal fault accuracy or certified safety operation.

equipment_diagnostics.adapters connects explicit contracts from process-monitoring-toolkit, h2physics and pipeline-safety-toolkit. See pinned revisions and examples/project_bridge.py. Object/serialization checks are separate from native-solver or plant validation. rotorvibe was inspected; no tested adapter to it is claimed here.

Development history, reproduction and continuation

Historical hash audits require the matching source snapshot, data and environment. Do not overwrite old results with current code while presenting them as an unchanged historical run. The v0.16 original-code snapshot and selected aggregate audit/protocol records are preserved in evidence/. Excluded local artifacts have a hash-only inventory; that inventory is not a public raw-data mirror or a complete reproduction bundle.

Rights and citation

Original code and original documentation are MIT. Raw datasets, downloaded papers, external source checkouts and fitted corpus profiles are excluded. External materials and optional dependencies retain their own terms. Scientific model names, equations, citations and required licence notices remain visible. Rewording text is not copyright clearance. See THIRD_PARTY_NOTICES and CITATION.cff.

This is original screening software inspired by identified physical/statistical principles, not a claim to reproduce every cited paper or a proprietary vendor classifier. Continue development from the documented failed candidates and evidence gaps, keeping measured validation, simulation, raw detection and alarm-policy effects distinct.