equinor/neqsim — Gitpedia

<h1> <img src="https://github.com/equinor/neqsim/blob/master/docs/wiki/neqsimlogocircleflatsmall.png" alt="NeqSim Logo" width="120" valign="middle"> NeqSim </h1> From Simulation Models to AI-Assisted Industrial Workflows <a href="https://github.com/equinor/neqsim/actions/workflows/verify_build.yml?query=branch%3Amaster"><img src="https://img.shields.io/github/actions/workflow/status/equinor/neqsim/verify_build.yml?branch=master&label=CI%20Build&logo=github" alt="CI Build"></a> <a href="https://search.maven.org/search?q=g:%22com.equinor.neqsim%22%20AND%20a:%22neqsim%22"><img src="https://img.shields.io/maven-central/v/com.equinor.neqsim/neqsim.svg?label=Maven%20Central" alt="Maven Central"></a> <a href="https://codecov.io/gh/equinor/neqsim"><img src="https://codecov.io/gh/equinor/neqsim/branch/master/graph/badge.svg" alt="Coverage"></a> <a href="https://github.com/equinor/neqsim/security/code-scanning"><img src="https://img.shields.io/github/actions/workflow/status/equinor/neqsim/codeql.yml?branch=master&label=CodeQL&logo=github" alt="CodeQL"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a> <a href="https://github.com/codespaces/new?hide_repo_select=true&ref=master&repo=equinor/neqsim"><img src="https://img.shields.io/badge/Open_in-Codespaces-blue?logo=github" alt="Open in Codespaces"></a> <a href="https://colab.research.google.com/drive/1XkQ_CrVj2gLTtJvXhFQMWALzXii522CL"><img src="https://img.shields.io/badge/Open_in-Colab-F9AB00?logo=googlecolab" alt="Open in Colab"></a> <a href="#quick-start">Quick Start</a> | <a href="#what-can-you-do-with-neqsim">Use Cases</a> | <a href="#agentic-engineering--mcp-server">AI / MCP</a> | <a href="#use-neqsim-in-java">Java</a> | <a href="#use-neqsim-in-python">Python</a> | <a href="#develop--contribute">Contribute</a> | <a href="https://equinor.github.io/neqsim/">Docs</a>

What is NeqSim?

NeqSim (Non-Equilibrium Simulator) is a comprehensive Java library for fluid property estimation, process simulation, and engineering design. It covers the full process engineering workflow, from thermodynamic modeling and PVT analysis through equipment sizing, pipeline flow, safety studies, and field development economics.

Developed at NTNU and maintained by Equinor, NeqSim is used for real-world oil & gas, carbon capture, hydrogen, and energy applications.

Use it from Java, Python, Jupyter notebooks, .NET, MATLAB, or let an AI agent drive it via natural language.

Key capabilities

Domain	What NeqSim provides
Thermodynamics	60+ equation-of-state models (SRK, PR, CPA, GERG-2008, and more), flash calculations (TP, PH, PS, dew, bubble), phase envelopes
Physical properties	Density, viscosity, thermal conductivity, surface tension, diffusion coefficients
Process simulation	33+ equipment types: separators, compressors, heat exchangers, valves, distillation columns, pumps, reactors
Pipeline & flow	Steady-state and transient multiphase pipe flow (Beggs & Brill, two-fluid model), pipe networks
PVT simulation	CME, CVD, differential liberation, separator tests, swelling tests, saturation pressure
Safety	Depressurization/blowdown, PSV sizing (API 520/521), source term generation, safety envelopes
Standards	ISO 6976 (gas quality), NORSOK, DNV, API, ASME compliance checks
Mechanical design	Wall thickness, weight estimation, cost analysis for pipelines, vessels, wells (SURF)
Field development	Production forecasting, concept screening, NPV/IRR economics, Monte Carlo uncertainty

See the full documentation, Java Wiki, or ask questions in Discussions.

Quick Start

Python - try it in 30 seconds

A Python wrapper is available on pip. Install using pip install neqsim.

See neqsim-python for more details.

Java - add to your project

Maven Central (simplest - no authentication needed):

xml
<dependency>
  <groupId>com.equinor.neqsim</groupId>
  <artifactId>neqsim</artifactId>
  <version>3.12.0</version>
</dependency>

java
import neqsim.thermo.system.SystemSrkEos;
import neqsim.thermodynamicoperations.ThermodynamicOperations;

SystemSrkEos fluid = new SystemSrkEos(273.15 + 25.0, 60.0);
fluid.addComponent("methane", 0.85);
fluid.addComponent("ethane", 0.10);
fluid.addComponent("propane", 0.05);
fluid.setMixingRule("classic");

ThermodynamicOperations ops = new ThermodynamicOperations(fluid);
ops.TPflash();
fluid.initProperties();

System.out.println("Density: " + fluid.getDensity("kg/m3") + " kg/m3");

AI agent - describe your problem in plain English

@solve.task hydrate formation temperature for wet gas at 100 bara

The agent scopes the task, builds a NeqSim simulation, validates results, and generates a Word + HTML report with no coding required.

What can you do with NeqSim?

<details> <summary>Calculate fluid properties</summary>

python
from neqsim import jneqsim

fluid = jneqsim.thermo.system.SystemSrkEos(273.15 + 15.0, 100.0)
fluid.addComponent("methane", 0.90)
fluid.addComponent("CO2", 0.05)
fluid.addComponent("nitrogen", 0.05)
fluid.setMixingRule("classic")

ops = jneqsim.thermodynamicoperations.ThermodynamicOperations(fluid)
ops.TPflash()
fluid.initProperties()

print(f"Density:      {fluid.getDensity('kg/m3'):.2f} kg/m3")
print(f"Molar mass:   {fluid.getMolarMass('kg/mol'):.4f} kg/mol")
print(f"Phases:       {fluid.getNumberOfPhases()}")

</details> <details> <summary>Simulate a process flowsheet</summary>

python
from neqsim import jneqsim

fluid = jneqsim.thermo.system.SystemSrkEos(273.15 + 30.0, 80.0)
fluid.addComponent("methane", 0.80)
fluid.addComponent("ethane", 0.12)
fluid.addComponent("propane", 0.05)
fluid.addComponent("n-butane", 0.03)
fluid.setMixingRule("classic")

Stream = jneqsim.process.equipment.stream.Stream
Separator = jneqsim.process.equipment.separator.Separator
Compressor = jneqsim.process.equipment.compressor.Compressor
ProcessSystem = jneqsim.process.processmodel.ProcessSystem

feed = Stream("Feed", fluid)
feed.setFlowRate(50000.0, "kg/hr")

separator = Separator("HP Separator", feed)
compressor = Compressor("Export Compressor", separator.getGasOutStream())
compressor.setOutletPressure(150.0, "bara")

process = ProcessSystem()
process.add(feed)
process.add(separator)
process.add(compressor)
process.run()

print(f"Compressor power: {compressor.getPower('kW'):.0f} kW")
print(f"Gas out temp:     {compressor.getOutletStream().getTemperature() - 273.15:.1f} C")

</details> <details> <summary>Predict hydrate formation temperature</summary>

python
from neqsim import jneqsim

fluid = jneqsim.thermo.system.SystemSrkEos(273.15 + 5.0, 80.0)
fluid.addComponent("methane", 0.90)
fluid.addComponent("ethane", 0.06)
fluid.addComponent("propane", 0.03)
fluid.addComponent("water", 0.01)
fluid.setMixingRule("classic")
fluid.setMultiPhaseCheck(True)

ops = jneqsim.thermodynamicoperations.ThermodynamicOperations(fluid)
ops.hydrateFormationTemperature()

print(f"Hydrate T: {fluid.getTemperature() - 273.15:.2f} C")

</details> <details> <summary>Run pipeline pressure-drop calculations</summary>

python
from neqsim import jneqsim

fluid = jneqsim.thermo.system.SystemSrkEos(273.15 + 40.0, 120.0)
fluid.addComponent("methane", 0.95)
fluid.addComponent("ethane", 0.05)
fluid.setMixingRule("classic")

Stream = jneqsim.process.equipment.stream.Stream
PipeBeggsAndBrills = jneqsim.process.equipment.pipeline.PipeBeggsAndBrills

feed = Stream("Inlet", fluid)
feed.setFlowRate(200000.0, "kg/hr")

pipe = PipeBeggsAndBrills("Export Pipeline", feed)
pipe.setPipeWallRoughness(5e-5)
pipe.setLength(50000.0)       # 50 km
pipe.setDiameter(0.508)        # 20 inch
pipe.setNumberOfIncrements(20)
pipe.run()

outlet = pipe.getOutletStream()
print(f"Outlet pressure: {outlet.getPressure():.1f} bara")
print(f"Outlet temp:     {outlet.getTemperature() - 273.15:.1f} C")

</details> <details> <summary>More examples</summary>

Explore 30+ Jupyter notebooks in examples/notebooks/:

Phase envelope calculation
TEG dehydration process
Vessel depressurization / blowdown
Heat exchanger thermal-hydraulic design
Production bottleneck analysis
Risk simulation and visualization
Data reconciliation and parameter estimation
Reservoir-to-export integrated workflows
Multiphase transient pipe flow

</details>

Agentic Engineering & MCP Server

LLMs reason well but hallucinate physics. NeqSim is exact on thermodynamics but needs context. Together, they form a complete engineering system. The LLM reasons. NeqSim computes. Provenance proves it.

MCP Server - give any LLM access to rigorous thermodynamics

The NeqSim MCP Server lets any MCP-compatible client (VS Code Copilot, Claude Desktop, Cursor, etc.) run real calculations. Install in seconds:

bash
# Docker (no Java needed)
docker pull ghcr.io/equinor/neqsim-mcp-server:latest

Ask the LLM	MCP Tool
"Dew point of 85% methane, 10% ethane, 5% propane at 50 bara?"	`runFlash`
"How does density change from 0 to 50 C at 80 bara?"	`runBatch`
"Phase envelope for this natural gas"	`getPhaseEnvelope`
"Simulate gas through a separator then compressor to 120 bara"	`runProcess`

Every response includes provenance metadata (EOS model, convergence, assumptions, limitations). See the MCP Server docs and setup guide.

AI task-solving workflow

@solve.task TEG dehydration sizing for 50 MMSCFD wet gas

The agent creates a task folder, runs NeqSim simulations, validates results, and generates a Word + HTML report with no coding required. See the tutorial or workflow reference.

Use NeqSim in Java

xml
<dependency>
  <groupId>com.equinor.neqsim</groupId>
  <artifactId>neqsim</artifactId>
  <version>3.12.0</version>
</dependency>

The Quick Start above shows the core pattern (create a fluid, run a flash, and read properties). For process simulation, add equipment to a ProcessSystem and call run(); see the Java Getting Started Guide for full examples.

Learn more: Java Getting Started Guide | JavaDoc | Wiki | Colab demo

Use NeqSim in Python

bash
pip install neqsim

NeqSim Python gives you direct access to the full Java API via the jneqsim gateway. All Java classes are available, including thermodynamics, process equipment, PVT, standards, and more.

python
from neqsim import jneqsim

# All Java classes accessible through jneqsim
SystemSrkEos = jneqsim.thermo.system.SystemSrkEos
ProcessSystem = jneqsim.process.processmodel.ProcessSystem
Stream = jneqsim.process.equipment.stream.Stream
# ... 200+ classes available

Explore 30+ ready-to-run Jupyter notebooks in examples/notebooks/.

Other language bindings

Language	Repository
Python	`pip install neqsim`
MATLAB	equinor/neqsimmatlab
.NET (C#)	equinor/neqsimcapeopen

Develop & Contribute

Clone and build

bash
git clone https://github.com/equinor/neqsim.git
cd neqsim
./mvnw install        # Linux/macOS
mvnw.cmd install      # Windows

Run tests

bash
./mvnw test                                    # all tests
./mvnw test -Dtest=SeparatorTest               # single class
./mvnw test -Dtest=SeparatorTest#testTwoPhase  # single method
./mvnw checkstyle:check spotbugs:check pmd:check  # static analysis

Code formatting (Spotless)

Java formatting is enforced by Spotless. CI runs a check-only gate (it never edits or pushes
your code), so format locally before pushing:

bash
./mvnw spotless:apply     # auto-format all Java files
./mvnw spotless:check      # verify formatting — must exit 0 before pushing

Optionally, install local pre-commit hooks to format on commit and verify on push (requires a
local JDK + Maven):

bash
pip install pre-commit
pre-commit install --hook-type pre-commit --hook-type pre-push
pre-commit run --all-files   # run hooks manually across the repo

See CONTRIBUTING.md for details.

Open in VS Code

The repository includes a ready-to-use dev container; just open the repo in VS Code with container support:

bash
git clone https://github.com/equinor/neqsim.git
cd neqsim
code .

Architecture

mermaid
graph TB
    subgraph core["NeqSim Core (Java 8+)"]
        THERMO["Thermodynamics<br/>60+ EOS models"]
        PROCESS["Process Simulation<br/>33+ equipment types"]
        PVT["PVT Simulation"]
        MECH["Mechanical Design<br/>& Standards"]
    end

    subgraph access["Access Layers"]
        PYTHON["Python / Jupyter<br/>pip install neqsim"]
        JAVA["Java / Maven<br/>Direct API"]
        MCP["MCP Server (Java 21+)<br/>LLM integration"]
        AGENTS["AI Agents<br/>VS Code Copilot"]
    end

    PYTHON --> THERMO
    PYTHON --> PROCESS
    JAVA --> THERMO
    JAVA --> PROCESS
    MCP --> THERMO
    MCP --> PROCESS
    AGENTS --> MCP
    AGENTS --> PYTHON

Which entry point should I use?

I want to...	Use	Requires
Quick property lookup via LLM	MCP Server + any LLM client	Java 21+ (or Docker)
Python scripting / Jupyter notebooks	`pip install neqsim`	Python 3.9+, JVM
Embed in a Java application	Maven dependency	Java 17+ (default) or Java 8+ (use the `-Java8` artifact)
Full engineering study with reports	`@solve.task` agent in VS Code	VS Code + GitHub Copilot
.NET / MATLAB integration	Language bindings	See linked repos

Java version matrix

Component	Java Version	Notes
NeqSim core library	17+ (default)	Default `neqsim` artifact targets Java 17 bytecode
NeqSim core library (`-Java8`)	8+	Java 8 compatible artifact built from `pomJava8.xml`
MCP server	21+	Quarkus-based; thin wrapper around core
Python users	No Java coding	JVM bundled via jpype
Running prebuilt MCP jar	21+	Download from releases

Core modules

Module	Package	Purpose
Thermodynamics	`thermo/`	60+ EOS implementations, flash calculations, phase equilibria
Physical properties	`physicalproperties/`	Density, viscosity, thermal conductivity, surface tension
Fluid mechanics	`fluidmechanics/`	Single- and multiphase pipe flow, pipeline networks
Process equipment	`process/equipment/`	33+ unit operations (separators, compressors, HX, valves, ...)
Chemical reactions	`chemicalreactions/`	Equilibrium and kinetic reaction models
Parameter fitting	`statistics/`	Regression, parameter estimation, Monte Carlo
Process simulation	`process/`	Flowsheet assembly, dynamic simulation, recycle/adjuster coordination

For details see docs/modules.md.

Contributing

We welcome contributions of all kinds: bug fixes, new models, examples, documentation, and notebook recipes.
AI-assisted PRs are first-class contributions; see CONTRIBUTING.md.

New here? Three commands to get started:

bash
git clone https://github.com/equinor/neqsim.git && cd neqsim
pip install -e devtools/    # one-time: registers the `neqsim` command
neqsim onboard             # interactive setup (Java, Maven, build, Python, agents)

Tip: Using a virtual environment (python -m venv .venv then activate it) avoids
PATH issues on all platforms. See devtools/README.md
if neqsim is not found, or use python -m neqsim_cli as a fallback.

Or skip local setup entirely: Open in GitHub Codespaces, with everything pre-installed in the browser.

Then explore and contribute:

bash
neqsim try                 # interactive playground - experiment with NeqSim instantly
neqsim contribute          # guided wizard - picks the right path for you
neqsim doctor              # quick diagnostic if something isn't working

CONTRIBUTING.md - Code of conduct, PR process, AI-assisted contributions
VISION_AGENTS.md - What belongs in the agentic system (core vs. community)
Developer setup guide - Build, test, and project structure
Contributing structure - Where to place code, tests, and resources

Where to start

Skills are markdown files containing engineering knowledge (code patterns, design rules, troubleshooting tips) that AI agents load automatically when solving related tasks. Contributing a skill is the easiest way to make the agentic system smarter, with no Java required.

#	First Contribution	Difficulty	What to do
1	Contribute a skill	Easy	Write a SKILL.md with domain knowledge - `neqsim new-skill "name"` (guide, example skill)
2	Add a NIST validation benchmark	Easy	Compare NeqSim flash results to NIST data in `docs/benchmarks/`
3	Create a Jupyter notebook example	Medium	Add a worked example to `examples/notebooks/`
4	Add an MCP example to the catalog	Easy	Add a new entry in `ExampleCatalog.java`
5	Fix a broken doc link	Easy	Search `docs/*/.md` for dead links and fix them
6	Add a unit test for existing equipment	Medium	Add tests under `src/test/java/neqsim/`

Community Skill and Agent Catalogs

Browse and install community-contributed skills, or publish your own:

bash
neqsim skill list                    # browse the catalog and discovered repositories
neqsim skill install <name>          # install a skill
neqsim skill publish user/repo-name  # publish yours (creates a draft PR)

Browse and install community-contributed agents separately from skills:

bash
neqsim agent list                    # browse installable agent workflows
neqsim agent search hydrate          # search by name, tag, description, or required skill
neqsim agent install <name>          # install an agent definition
neqsim agent install --all           # install every agent in the catalog
neqsim agent validate <name-or-path> # validate an installed or local agent package
neqsim agent schema                  # show the supported agent.yaml fields

The catalog can list individual skills directly and can also point to public
multi-skill GitHub repositories. When a repository is listed under
repositories: in community-skills.yaml, neqsim skill list reads the online
repo catalog first and falls back to scanning matching SKILL.md files, so new
skills can appear without adding one entry per skill to the NeqSim repo.

Agents follow the same discovery model through community-agents.yaml, but they
are kept as a separate install type. Skills are reusable engineering knowledge;
agents are role/workflow definitions that can declare required_skills and are
installed to ~/.neqsim/agents/. Agent packages can include an agent.yaml
manifest with supported domains, inputs, outputs, MCP tool requirements, human
review policy, and trust level. Installing an agent downloads and validates the
definition only; execution is an explicit action in the AI tool that uses it.

The shared public home for reusable community skills is
equinor/neqsim-community-skills.
The shared public home for reusable community agents is
equinor/neqsim-community-agents.
Put skills there when they are public, reproducible, useful beyond one project,
and do not need to live in NeqSim core. Good candidates include educational
screening workflows, public validation helpers, open engineering checklists,
agent guidance around existing NeqSim workflows, and examples with synthetic or
public data. Keep proprietary methods, plant data, private tag names, internal
URLs, company standards, and project-specific design bases out of the public
community repos; use private skill or agent catalogs for those.

See the Skills Guide for the full walkthrough,
community-skills.yaml and
community-agents.yaml for the catalogs, and
.github/skills/README.md for the quick contribution guide.

All tests and ./mvnw checkstyle:check must pass before a PR is merged.

Documentation & Resources

Resource	Link
User documentation	equinor.github.io/neqsim
Benchmark gallery	docs/benchmarks/ - validation against NIST, published data
Reference manual index	REFERENCE_MANUAL_INDEX.md (350+ pages)
MCP tool contract	MCP_CONTRACT.md - stable API for agent builders
JavaDoc API	JavaDoc
Jupyter notebooks	examples/notebooks/ (30+ examples)
Discussion forum	GitHub Discussions
Releases	GitHub Releases
NeqSim homepage	equinor.github.io/neqsimhome

Authors

Even Solbraa (esolbraa@gmail.com), Marlene Louise Lund

NeqSim development was initiated at NTNU. A number of master and PhD students have contributed to its development, and we greatly acknowledge their contributions.