equinor/neqsim

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

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):

<dependency>
  <groupId>com.equinor.neqsim</groupId>
  <artifactId>neqsim</artifactId>
  <version>3.16.0</version>
</dependency>

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?

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()}")

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")

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")

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")

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

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:

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

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.

Agents & skills — the extension ecosystem

Agentic NeqSim is built from two layers you can mix and extend:

• Skills = the knowledge layer. Structured markdown that encodes domain expertise (API patterns, decision rules, reference data). Agents read skills to know how to do something correctly.
• Agents = the workflow layer. A role + objective + the skills it loads. Agents drive NeqSim to complete a job (e.g. @solve.task, @field.development).

Content comes from four tiers — core (shipped in this repo under .github/skills and .github/agents, auto-loaded), community (public, installable), enterprise (company-private/internal), and local private (just you):

Ecosystem at a glance — how the pieces relate:

graph TD
    CORE["NeqSim core<br/>Java engine + .github/skills + .github/agents<br/>(auto-loaded)"]
    MCP["MCP Server<br/>rigorous calculations for any LLM"]
    CAG["Community agents<br/>public workflows"]
    CSK["Community skills<br/>public knowledge"]
    EAG["Enterprise agents / skills<br/>internal, company-private"]
    PRIV["Local private<br/>~/.neqsim (just you)"]
    VSC["VS Code Copilot / Claude / Cursor / Codex"]

    CORE --> MCP
    CAG --> CSK
    EAG --> CSK
    CSK --> CORE
    CAG --> CORE
    EAG --> CORE
    PRIV --> CORE
    CORE -->|neqsim agent/skill install| VSC
    MCP --> VSC

Install and use them with the neqsim CLI (all user-scope, no admin — see the no-admin runbook):

neqsim agent list                 # browse the community catalog
neqsim agent search hydrate       # find an agent by keyword
neqsim agent install --all --vscode   # export agents+skills to ~/.copilot for VS Code Copilot
neqsim skill install --all        # install community skills

neqsim agent private-init         # scaffold a private/enterprise catalog
# ...or register a private repo AND sign in with browser SSO in one step:
neqsim agent private-init --repo my-org/neqsim-enterprise-agents --login
neqsim skill private-init --repo my-org/neqsim-enterprise-skills --login

• How internal (enterprise) content works: a company publishes private enterprise-agents.yaml / enterprise-skills.yaml in governed internal repos. These are never committed to the public NeqSim repos; they are discovered per-user (via ~/.neqsim/private-*.yaml and gh-CLI / Git Credential Manager auth). private-init writes and then prints the path to those per-user files (~/.neqsim/private-agents.yaml / private-skills.yaml) so you can edit them afterwards. See Enterprise Agent & Skill Repositories.
• Full details: the Skills & Agents Guide explains the four tiers, packaging, canonical installs vs tool exports, and how to author your own.

Where does a new skill or agent go? (recommendation for how to work)

Decide by coupling and confidentiality, not by "coding vs using":

One-line test: validated & API-coupled → this repo · educational screening → community · company policy or confidential → enterprise/private. See VISION_AGENTS.md and the Where Does This Go? guide for the full decision tree.

Use NeqSim in Java

<dependency>
  <groupId>com.equinor.neqsim</groupId>
  <artifactId>neqsim</artifactId>
  <version>3.16.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

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.

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

Develop & Contribute

Clone and build

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

Windows: enable long paths before cloning. Maven's target/ directory can produce paths longer than the legacy 260-character limit, causing checkout or build errors. Enable long-path support once (user-scope, no admin required):

git config --global core.longpaths true

Also prefer cloning inside your user profile (e.g. C:\Users\<id>\Documents\GitHub\neqsim) rather than a short drive root, and avoid C:\Program Files (which needs elevated rights to write).

Restricted / corporate PC (no admin rights)

Everything below installs into your user profile and needs no administrator rights — the common situation on locked-down corporate PCs. Prerequisites (Git, Python, a JDK, VS Code) must already be provisioned per-user (e.g. via your software portal or winget --scope user).

# 0. One-time Git setting (user-scope, no admin)
git config --global core.longpaths true

# 1. Clone into your user profile
cd $HOME\Documents\GitHub
git clone https://github.com/equinor/neqsim.git
cd neqsim

# 2. Python devtools in a venv (keeps the 'neqsim' command on PATH)
py -3 -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned   # per-process, no admin
.\.venv\Scripts\Activate.ps1
.\install.ps1
neqsim doctor          # verifies Python, Java/JDK, Maven wrapper, agents

# 3. Java build — needs a JDK. No admin? Let the installer fetch a PORTABLE JDK:
.\install.ps1 -InstallJdk       # downloads Temurin into ~/.neqsim\jdk, sets user env vars
# (or install a JDK manually and set JAVA_HOME yourself), then in a NEW terminal:
.\mvnw.cmd install -DskipTests

# 4. Install AI agents into ~/.copilot for VS Code Copilot (no admin)
neqsim agent install --all --vscode
neqsim skill install --all

Run tests

./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:

./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):

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:

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

Architecture

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?

Java version matrix

Core modules

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? Get started (Windows, PowerShell):

git clone https://github.com/equinor/neqsim.git
cd neqsim
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1   # activate the venv FIRST so 'neqsim' lands on PATH
.\install.cmd                  # or .\install.ps1  (append 'uv' for the fast installer)
neqsim onboard                 # interactive setup (Java, Maven, build, Python, agents)

macOS/Linux:

git clone https://github.com/equinor/neqsim.git && cd neqsim
python3 -m venv .venv && source .venv/bin/activate
./install.sh
neqsim onboard

Activate the venv before running install. The installer does not create or activate a venv — it only detects an already-active one. Activating first means the package and the neqsim command install into the venv and stay on PATH; skip it and you may hit "neqsim is not recognized".

The install script finds a working Python for you and runs python -m pip under the hood, so it works even when pip/python are not on PATH. To install manually, use python -m pip install -e devtools/ (not bare pip).

Windows: "install.ps1 is not digitally signed" error? This is PowerShell's execution policy, not a problem with the file. Run the pure-batch installer .\install.cmd (calls Python/pip directly, works even when the policy is locked by Group Policy), or just run py -m pip install -e devtools/.

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:

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.

Public, reusable skills and agents live in their own community repos — equinor/neqsim-community-skills and equinor/neqsim-community-agents — while company-private ones go in internal enterprise repos (see below).

Community Skill and Agent Catalogs

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

neqsim skill list                    # browse the catalog and discovered repositories
neqsim skill install <name>          # install a skill
neqsim skill install <name> --target vscode   # also export to your ~/.copilot/skills folder
neqsim skill doctor                  # check private-catalog authentication readiness
neqsim skill doctor --target vscode  # verify VS Code skill exports
neqsim skill publish user/repo-name  # publish yours (creates a draft PR)

Browse and install community-contributed agents separately from skills:

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 <name> --target vscode   # also export the agent and required skills for VS Code
neqsim agent install --all           # install every agent in the catalog
neqsim agent doctor --target vscode  # verify VS Code exports and required skill visibility
neqsim agent validate <name-or-path> # validate an installed or local agent package
neqsim agent schema                  # show the supported agent.yaml fields

Both neqsim agent doctor --target ... and neqsim skill doctor --target ... accept --profile path/to/export-profile.json to check a declared export set. Without a profile, missing exports are warnings; with a profile, expected-but-missing exports are errors and extra exports are warnings.

By default, installed community and private content is kept out of the Git-tracked workspace: skills install to ~/.neqsim/skills/, agents install to ~/.neqsim/agents/, and --target vscode writes generated copies to the personal ~/.copilot/skills and ~/.copilot/agents folders (which VS Code and the GitHub Copilot CLI scan in every workspace). Use --vscode-scope workspace only when a maintainer intentionally wants a generated .github/skills or .github/agents copy.

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 enterprise skill and agent repositories for those.

See Setting up Agents and Skills for the start-here install walkthrough, the Skills Guide for the full walkthrough, Enterprise Agent and Skill Repositories for company-private repository setup, 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

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.

License

Apache-2.0