README

Install, deploy, and integrate Deep Safety.

This page mirrors the repository README. It describes Deep Safety as a physics-based process safety platform designed for direct integration into software systems and engineering workflows.

What it is

Deep Safety is a process safety computation layer for consequence analysis, hazard evaluation, and decision support. It exposes one model contract and one constants framework across package, API, browser, notebook, and MCP usage.

Modeling chain

Materials and operating/design data are the upstream foundation
Scenario definition and source models create the release term
Dispersion and effects use that release term downstream
Hazard-evaluation workflows consume the physical outputs explicitly

Package and runtime

pip install deepsafety
pip install "deepsafety[jupyter]"

deepsafety-api
deepsafety-mcp
python -m deepsafety

The package, API, browser application, and MCP server use the same model vocabulary and constants system.

Deployment options

GitHub Pages for the static web experience
Docker container for the FastAPI service
Local Python install for notebooks and scripts
MCP server for tool-driven and agent-driven use

Container quick start

docker build -t deepsafety .
docker run --rm -p 8000:8000 deepsafety

# or
docker compose up --build

Notebook entry point

Use notebooks/deepsafety_explorer.ipynb or import the package directly in Jupyter for model discovery and quick calculations.

Documentation site: deepsafety.tech

Documentation Site

Documentation, application surfaces, and installation guidance are separated for faster adoption.

Reference: use API Reference for module families, endpoint groups, equations, and constant provenance.

Learning: use Tutorials and Use Cases for onboarding, worked examples, and application patterns.

Current model coverage

Aligned with the current repository build.

Data, source, and dispersion

Material records for toxicity, flammability, and reactivity starter data
Gas release: choked, non-choked, pipe, hole, relief, vessel blowdown
Liquid release: tank hole, pipe flow, gravity-driven, pressure-driven
Flashing and two-phase screening
Pool formation and evaporation screening
Gaussian plume, Gaussian puff, dense-gas screening
Isopleths, toxic-endpoint evaluation, and mitigation-adjusted dispersion

Hazards, safeguards, and studies

Flammability mixture, LOC, and ignition energy screening
Jet fire, pool fire, fireball BLEVE
TNT equivalency, multi-energy, VCE
Toxic, thermal, and explosion probit models
Toxic, thermal, and explosion dose-response curves
Prevention, reactivity, and relief-system analysis endpoints
HAZOP, FMEA, What-If, checklist, and input-validation workflows

Physics transparency

Equations and constants are intended to be surfaced inside applications, not hidden behind abstractions.

shared.gravity_standard: gravity driving hydrostatic liquid discharge.
shared.universal_gas_constant: gas-state relation used in compressible source terms.
fire.default_radiative_fraction: share of fire energy treated as radiant heat.
fire.default_atmospheric_transmissivity: share of radiation assumed to reach the receptor.
Starter registries are packaged as JSON files rather than being embedded directly in Python code.

Documentation split

Deep Safety keeps app, API docs, and README guidance on separate Pages routes.

app.html for the browser-local interactive tool
api-docs.html for endpoint-first integration guidance
readme.html for installation and repository-level overview