Metadata-Version: 2.4
Name: api581-engine
Version: 0.1.4
Summary: API RP 581 Risk Analysis Module: composable Python calculations and workflows
License: Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
           "License" shall mean the terms and conditions for use, reproduction, and
           distribution as defined by Sections 1 through 9 of this document.
        
           "Licensor" shall mean the copyright owner or entity authorized by the
           copyright owner that is granting the License.
        
           "Legal Entity" shall mean the union of the acting entity and all other
           entities that control, are controlled by, or are under common control with
           that entity. For the purposes of this definition, "control" means (i) the
           power, direct or indirect, to cause the direction or management of such
           entity, whether by contract or otherwise, or (ii) ownership of fifty
           percent (50%) or more of the outstanding shares, or (iii) beneficial
           ownership of such entity.
        
           "You" (or "Your") shall mean an individual or Legal Entity exercising
           permissions granted by this License.
        
           "Source" form shall mean the preferred form for making modifications,
           including but not limited to software source code, documentation source,
           and configuration files.
        
           "Object" form shall mean any form resulting from mechanical transformation
           or translation of a Source form, including but not limited to compiled
           object code, generated documentation, and conversions to other media types.
        
           "Work" shall mean the work of authorship, whether in Source or Object form,
           made available under the License, as indicated by a copyright notice that
           is included in or attached to the work (an example is provided in the
           Appendix below).
        
           "Derivative Works" shall mean any work, whether in Source or Object form,
           that is based on (or derived from) the Work and for which the editorial
           revisions, annotations, elaborations, or other modifications represent, as
           a whole, an original work of authorship. For the purposes of this License,
           Derivative Works shall not include works that remain separable from, or
           merely link (or bind by name) to the interfaces of, the Work and Derivative
           Works thereof.
        
           "Contribution" shall mean any work of authorship, including the original
           version of the Work and any modifications or additions to that Work or
           Derivative Works thereof, that is intentionally submitted to Licensor for
           inclusion in the Work by the copyright owner or by an individual or Legal
           Entity authorized to submit on behalf of the copyright owner. For the
           purposes of this definition, "submitted" means any form of electronic,
           verbal, or written communication sent to the Licensor or its
           representatives, including but not limited to communication on electronic
           mailing lists, source code control systems, and issue tracking systems that
           are managed by, or on behalf of, the Licensor for the purpose of discussing
           and improving the Work, but excluding communication that is conspicuously
           marked or otherwise designated in writing by the copyright owner as "Not a
           Contribution."
        
           "Contributor" shall mean Licensor and any individual or Legal Entity on
           behalf of whom a Contribution has been received by Licensor and
           subsequently incorporated within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of this
           License, each Contributor hereby grants to You a perpetual, worldwide,
           non-exclusive, no-charge, royalty-free, irrevocable copyright license to
           reproduce, prepare Derivative Works of, publicly display, publicly perform,
           sublicense, and distribute the Work and such Derivative Works in Source or
           Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of this
           License, each Contributor hereby grants to You a perpetual, worldwide,
           non-exclusive, no-charge, royalty-free, irrevocable (except as stated in
           this section) patent license to make, have made, use, offer to sell, sell,
           import, and otherwise transfer the Work, where such license applies only to
           those patent claims licensable by such Contributor that are necessarily
           infringed by their Contribution(s) alone or by combination of their
           Contribution(s) with the Work to which such Contribution(s) was submitted.
        
        4. Redistribution. You may reproduce and distribute copies of the Work or
           Derivative Works thereof in any medium, with or without modifications, and
           in Source or Object form, provided that You meet the following conditions:
        
           (a) You must give any other recipients of the Work or Derivative Works a
               copy of this License; and
        
           (b) You must cause any modified files to carry prominent notices stating
               that You changed the files; and
        
           (c) You must retain, in the Source form of any Derivative Works that You
               distribute, all copyright, patent, trademark, and attribution notices
               from the Source form of the Work, excluding those notices that do not
               pertain to any part of the Derivative Works; and
        
           (d) If the Work includes a "NOTICE" text file as part of its distribution,
               then any Derivative Works that You distribute must include a readable
               copy of the attribution notices contained within such NOTICE file,
               excluding those notices that do not pertain to any part of the
               Derivative Works, in at least one of the following places: within a
               NOTICE text file distributed as part of the Derivative Works; within
               the Source form or documentation, if provided along with the
               Derivative Works; or, within a display generated by the Derivative
               Works, if and wherever such third-party notices normally appear. The
               contents of the NOTICE file are for informational purposes only and do
               not modify the License. You may add Your own attribution notices within
               Derivative Works that You distribute, alongside or as an addendum to
               the NOTICE text from the Work, provided that such additional
               attribution notices cannot be construed as modifying the License.
        
           You may add Your own copyright statement to Your modifications and may
           provide additional or different license terms and conditions for use,
           reproduction, or distribution of Your modifications, or for any such
           Derivative Works as a whole, provided Your use, reproduction, and
           distribution of the Work otherwise complies with the conditions stated in
           this License.
        
        5. Submission of Contributions. Unless You explicitly state otherwise, any
           Contribution intentionally submitted for inclusion in the Work by You to
           the Licensor shall be under the terms and conditions of this License,
           without any additional terms or conditions. Notwithstanding the above,
           nothing herein shall supersede or modify the terms of any separate license
           agreement you may have executed with Licensor regarding such Contributions.
        
        6. Trademarks. This License does not grant permission to use the trade names,
           trademarks, service marks, or product names of the Licensor, except as
           required for reasonable and customary use in describing the origin of the
           Work and reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
           writing, Licensor provides the Work (and each Contributor provides its
           Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
           ANY KIND, either express or implied, including, without limitation, any
           warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
           FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
           determining the appropriateness of using or redistributing the Work and
           assume any risks associated with Your exercise of permissions under this
           License.
        
        8. Limitation of Liability. In no event and under no legal theory, whether in
           tort (including negligence), contract, or otherwise, unless required by
           applicable law (such as deliberate and grossly negligent acts) or agreed to
           in writing, shall any Contributor be liable to You for damages, including
           any direct, indirect, special, incidental, or consequential damages of any
           character arising as a result of this License or out of the use or
           inability to use the Work (including but not limited to damages for loss of
           goodwill, work stoppage, computer failure or malfunction, or any and all
           other commercial damages or losses), even if such Contributor has been
           advised of the possibility of such damages.
        
        9. Accepting Warranty or Additional Liability. While redistributing the Work
           or Derivative Works thereof, You may choose to offer, and charge a fee for,
           acceptance of support, warranty, indemnity, or other liability obligations
           and/or rights consistent with this License. However, in accepting such
           obligations, You may act only on Your own behalf and on Your sole
           responsibility, not on behalf of any other Contributor, and only if You
           agree to indemnify, defend, and hold each Contributor harmless for any
           liability incurred by, or claims asserted against, such Contributor by
           reason of your accepting any such warranty or additional liability.
        
        END OF TERMS AND CONDITIONS
        
Keywords: api-581,risk-based-inspection,rbi,asset-integrity,process-safety
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: pydantic<3,>=2.9
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Provides-Extra: source
Requires-Dist: pypdf<7,>=5; extra == "source"
Provides-Extra: flash
Requires-Dist: CoolProp==8.0.0; extra == "flash"
Provides-Extra: slabx
Requires-Dist: slabx==1.0.8; extra == "slabx"
Provides-Extra: slabx-lh2
Requires-Dist: slabx==1.0.8; extra == "slabx-lh2"
Requires-Dist: slabx-lh2==0.2.0; extra == "slabx-lh2"
Provides-Extra: hpc-sqlite
Requires-Dist: pysqlite3-binary==0.5.4.post2; platform_system == "Linux" and extra == "hpc-sqlite"
Dynamic: license-file

# API RP 581 Risk Analysis Module

An unofficial, independently authored Python implementation of API-RP-581
risk-based inspection calculations and composable risk workflows.

> **Important legal and engineering notice**
>
> This project is not affiliated with or endorsed by the American Petroleum
> Institute. `API`, `API RP 581`, and related marks belong to their respective
> owners. The repository does not redistribute API standards or purchased
> source documents. Obtain the applicable standard under your own license.
> Results are software calculations, not a fitness-for-service decision,
> inspection release, operating authorization, or safety certification.
> Applicability, input quality, engineering assumptions, and site acceptance
> remain the user's responsibility.

## What this package provides

The package is published as `api581-engine` and imported as `api581`.
The project display name is **API RP 581 Risk Analysis Module**.

- 509 typed calculation registrations with Pydantic input/output contracts
- 861 API-RP-581 source-section records with section → calculation → test
  traceability
- Individual calculations and composable integrated workflows
- Level 1/Level 2 consequence and risk composition boundaries
- Four representative release-hole paths, effects, financial consequence,
  probability/frequency and portfolio aggregation APIs
- Optional SLABx 1.0.8 and SLABx-LH2 0.2.0 process-isolated adapters
- API 520 capacity-sizing utilities kept as a clearly separated companion
  namespace
- Digital-twin schemas, catalog queries, validation evidence and JSON receipts
- Reproducible local and Nurion PBS verification scripts

The current release is software-verified with external evaluation explicitly
out of project scope. It is not a third-party API conformity certificate.

## Install

```bash
python -m pip install api581-engine
```

For development and the full test suite:

```bash
python -m pip install -e ".[test]"
python -m pytest -q
```

Optional capabilities:

```bash
python -m pip install -e ".[source]"      # read local PDF source metadata
python -m pip install -e ".[flash]"       # CoolProp pure-fluid routes
python -m pip install -e ".[slabx]"       # SLABx 1.0.8 adapter
python -m pip install -e ".[slabx-lh2]"   # SLABx-LH2 0.2.0 boundary
```

The optional native packages are never silently replaced by an alternate
engine. Missing packages produce an explicit capability status or a typed
optional-engine error.

## Quick start

Every public calculation has a typed `*Input` model and a typed result. The
registry, schemas and catalog are available without learning internal module
layout.

```python
from api581 import Context
from api581.api import release

result = release.gas(
    release.GasInput(
        diameter_m=0.0254,
        upstream_pressure_pa_abs=1_000_000,
        temperature_k=300,
        molecular_weight_kg_kmol=23,
        heat_capacity_ratio=1.3,
    ),
    context=Context(asset_id="pipe-001"),
)

print(result.outputs.mass_rate_kg_s)
print(result.references)
print(result.limitations)
print(result.validation_evidence)
```

For a discoverable interface:

```python
from api581 import calculation_catalog, calculation_evidence

for item in calculation_catalog(domain="risk"):
    print(item.calculation_id, item.title, item.python_path)

print(calculation_evidence("risk/assessment"))
```

## Complete module map

All calculation IDs, Python paths, input/output schemas, references,
limitations and direct-test links are in [`docs/MODULE_CATALOG.md`](docs/MODULE_CATALOG.md)
and `src/api581/data/python-api.schema.json`.

| Domain | Scope |
|---|---|
| `frequency` | generic, adjusted and management/system failure frequencies |
| `damage` | thinning, cracking, corrosion, HTHA, brittle, fatigue and mechanism screening |
| `inspection` | effectiveness, equivalence, history and coverage factors |
| `reliability` | Poisson, Weibull, renewal and failure-history primitives |
| `release` | gas/liquid/two-phase release rates, holes, isolation and source partition |
| `properties` | representative fluids, mixtures, saturation and flash contracts |
| `effects` | jet fire, pool fire, flash fire, fireball, BLEVE, blast and radiation |
| `events` | ignition, mitigation, PRD and event-tree primitives |
| `consequence` | release, toxic, flammable, environmental and financial consequence composition |
| `financial` | repair, cleanup, business interruption and monetary aggregation |
| `risk` | POF/COF integration, risk matrices, portfolio and damage handoff |
| `planning` | target crossing and inspection-planning primitives |
| `level1` | Level 1 flammable/toxic consequence summaries |
| `level2` | Level 2 source, scenario, dispersion and consequence summaries |
| `prd` | relief-device history, leakage, failure and consequence boundaries |
| `tank` | atmospheric-tank inventory, shell/bottom thinning, environment and finance |
| `dispersion` | grids, source handoff and optional SLABx/SLABx-LH2 native boundaries |
| `api520` | companion pressure-relief capacity and sizing utilities; outside the API-581 clause ledger |

Each domain has focused validation notes under [`docs/`](docs/), including
the acid/sour/amine/CO2/HF/HCl/sulfidic mechanisms, tank routes, two-phase
events, native dispersion, radiation, blast, inspection and thinning models.

## Integrated workflow

The library deliberately separates calculations from orchestration. Use
individual functions for auditable steps, or use `Workflow`, `Step` and
`run_workflow` for a declarative graph. A risk assessment consumes explicitly
qualified damage factors and four-hole consequence outputs; it does not invent
plant applicability, inspection data, material properties or FFS conclusions.

```python
from api581.workflow import Step, Workflow, run_workflow

workflow = Workflow(steps=[
    Step(id="release", calculation_id="release/gas", input={...}),
    Step(id="risk", calculation_id="risk/assessment", input={...}),
])
result = run_workflow(workflow)
```

See [`examples/`](examples/) for direct composition, risk handoff, tank,
source partition, native dispersion, toxic and inspection-planning examples.

## SLABx and SLABx-LH2 boundary

Native engines are optional and process-isolated. The adapter records package
version/importability, source fingerprints, actual grid extent, censoring and
premise diagnostics. It does not claim that a native result is a site model,
does not apply an invented LH2 safety factor, and does not silently fall back
to another dispersion engine. See:

- [`docs/NATIVE_DISPERSION_VALIDATION.md`](docs/NATIVE_DISPERSION_VALIDATION.md)
- [`docs/NATIVE_JET_VALIDATION.md`](docs/NATIVE_JET_VALIDATION.md)
- [`docs/NATIVE_FOOTPRINT_VALIDATION.md`](docs/NATIVE_FOOTPRINT_VALIDATION.md)
- [`docs/NATIVE_ENGINE_EVIDENCE.json`](docs/NATIVE_ENGINE_EVIDENCE.json)

## Verification and reproducibility

Local release verification:

```powershell
python scripts/final_audit.py
python scripts/verify_provenance.py
python scripts/verify_completion_matrix.py
python -m twine check tmp/release-final-20261025br/*
```

Current evidence includes:

- 11,848 passing tests and 3 optional skips
- 108 reference fixtures
- 509/509 direct test references
- canonical Nurion PBS receipt: 64/64 shards passed
- efficient Nurion receipt: 10/10 shards passed
- 16,000 broad input invariant cases
- native suite: 9/9 scripts passed
- 66 supporting-text clauses machine-reviewed and 10 public-data reviewed

The reproducibility and handoff record is in:

- [`docs/FINAL_AUDIT.md`](docs/FINAL_AUDIT.md)
- [`docs/COMPLETION_AUDIT.md`](docs/COMPLETION_AUDIT.md)
- [`docs/completion-matrix.json`](docs/completion-matrix.json)
- [`docs/release-manifest.json`](docs/release-manifest.json)
- [`docs/DEVELOPMENT_STATUS.md`](docs/DEVELOPMENT_STATUS.md)
- [`docs/VERIFICATION_COMMANDS.md`](docs/VERIFICATION_COMMANDS.md)

## Copyright and public-release boundary

The public release contains original implementation code, original
documentation, generated schemas, hashes and test receipts. It intentionally
does **not** include API standard PDFs, DOCX files, purchased tables or copied
standard text. Source-document filenames, byte counts and SHA-256 fingerprints
are retained only as provenance metadata where needed.

Read [`NOTICE.md`](NOTICE.md) and [`COPYRIGHT.md`](COPYRIGHT.md) before
redistributing or adding fixtures. The Apache-2.0 license applies to original
repository work only; it does not license API standards or third-party source
documents.

## Development handoff

Start with [`docs/DEVELOPMENT_STATUS.md`](docs/DEVELOPMENT_STATUS.md), then
read [`docs/MODULE_CATALOG.md`](docs/MODULE_CATALOG.md),
[`docs/completion-matrix.json`](docs/completion-matrix.json), and the final
audit receipt. New calculations must register a typed input/output contract,
references, limitations, direct tests and both directions of traceability.
Do not commit local source PDFs, credentials, runtime databases, Nurion working
directories or generated build folders.

## License

Original code and documentation are licensed under [Apache License 2.0](LICENSE).
See [`NOTICE.md`](NOTICE.md) for trademarks, standards and third-party-source
boundaries.
