equinor/neqsim-python — Gitpedia

<h1> <img src="https://github.com/equinor/neqsim/blob/master/docs/wiki/neqsimlogocircleflatsmall.png" alt="NeqSim Logo" width="120" valign="middle"> NeqSim Python </h1> Python interface to the NeqSim engine — fluid properties, process simulation, and PVT analysis from Python and Jupyter notebooks. <a href="https://github.com/equinor/neqsim-python/actions/workflows/runtests.yml?query=branch%3Amaster"><img src="https://github.com/equinor/neqsim-python/actions/workflows/runtests.yml/badge.svg?branch=master" alt="Tests"></a> <a href="https://github.com/equinor/neqsim-python/actions/workflows/publish-to-test-pypi.yml"><img src="https://github.com/equinor/neqsim-python/actions/workflows/publish-to-test-pypi.yml/badge.svg?branch=master" alt="Publish"></a> <a href="https://pypi.org/project/neqsim/"><img src="https://img.shields.io/pypi/v/neqsim.svg?label=PyPI" alt="PyPI"></a> <a href="https://pypi.org/project/neqsim/"><img src="https://img.shields.io/pypi/pyversions/neqsim.svg" alt="Python"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a> <a href="#-quick-start">Quick Start</a> · <a href="#-process-simulation">Process Simulation</a> · <a href="#-pvt-simulation">PVT Simulation</a> · <a href="#-examples">Examples</a> · <a href="https://equinor.github.io/neqsimhome/">Docs</a> · <a href="https://github.com/equinor/neqsim/discussions">Community</a>

What is NeqSim Python?

NeqSim Python is part of the NeqSim project — a Python interface to the NeqSim Java library for estimation of fluid behavior and process design for oil and gas production. For an introduction see Introduction to Process Modelling with NeqSim in Python.

It provides Python toolboxes such as thermoTools and processTools that streamline the use of NeqSim, plus direct access to the full Java API via the jneqsim gateway.

Capability	What you get
Thermodynamics	60+ EOS models (SRK, PR, CPA, GERG-2008, …), flash calculations, phase envelopes
Physical properties	Density, viscosity, thermal conductivity, surface tension
Process simulation	33+ equipment types — separators, compressors, heat exchangers, valves, pumps, reactors
PVT simulation	CME, CVD, differential liberation, separator tests, swelling, viscosity
Pipeline & flow	Steady-state multiphase pipe flow (Beggs & Brill), pipe networks

🚀 Quick Start

Install

<table> <tr><td>pip (requires Java 11+)</td><td>conda (Java included)</td></tr> <tr> <td>

bash
pip install neqsim

</td> <td>

bash
conda install -c conda-forge neqsim

</td> </tr> </table>

Prerequisites: Python 3.9+ and Java 11+. The conda package automatically installs OpenJDK — no separate Java setup needed. For pip, install Java from Adoptium.

Try it now

python
from neqsim.thermo import fluid, TPflash, printFrame

# Create a natural gas fluid
fl = fluid('srk')
fl.addComponent('methane', 0.85)
fl.addComponent('ethane', 0.10)
fl.addComponent('propane', 0.05)
fl.setTemperature(25.0, 'C')
fl.setPressure(60.0, 'bara')
fl.setMixingRule('classic')

TPflash(fl)
printFrame(fl)

print(f"Gas density:    {fl.getPhase('gas').getDensity('kg/m3'):.2f} kg/m3")
print(f"Gas viscosity:  {fl.getPhase('gas').getViscosity('kg/msec'):.6f} kg/(m*s)")
print(f"Z-factor:       {fl.getPhase('gas').getZ():.4f}")

🔧 Process Simulation

NeqSim Python provides multiple ways to build process simulations:

<details> <summary>1. Python Wrappers — recommended for beginners & notebooks</summary>

Simple functions with a global process — great for prototyping:

python
from neqsim.thermo import fluid
from neqsim.process import stream, compressor, separator, runProcess, clearProcess

clearProcess()
feed = fluid('srk')
feed.addComponent('methane', 0.9)
feed.addComponent('ethane', 0.1)
feed.setTemperature(30.0, 'C')
feed.setPressure(50.0, 'bara')
feed.setTotalFlowRate(10.0, 'MSm3/day')

inlet = stream('inlet', feed)
sep = separator('separator', inlet)
comp = compressor('compressor', sep.getGasOutStream(), pres=100.0)
runProcess()

print(f"Compressor power: {comp.getPower()/1e6:.2f} MW")

</details> <details> <summary>2. ProcessContext — recommended for production code</summary>

Context manager with explicit process control — supports multiple independent processes:

python
from neqsim.thermo import fluid
from neqsim.process import ProcessContext

feed = fluid('srk')
feed.addComponent('methane', 0.9)
feed.addComponent('ethane', 0.1)
feed.setTemperature(30.0, 'C')
feed.setPressure(50.0, 'bara')

with ProcessContext("Compression Train") as ctx:
    inlet = ctx.stream('inlet', feed)
    sep = ctx.separator('separator', inlet)
    comp = ctx.compressor('compressor', sep.getGasOutStream(), pres=100.0)
    ctx.run()
    print(f"Compressor power: {comp.getPower()/1e6:.2f} MW")

</details> <details> <summary>3. ProcessBuilder — fluent API for configuration-driven design</summary>

Chainable builder pattern:

python
from neqsim.thermo import fluid
from neqsim.process import ProcessBuilder

feed = fluid('srk')
feed.addComponent('methane', 0.9)
feed.addComponent('ethane', 0.1)
feed.setTemperature(30.0, 'C')
feed.setPressure(50.0, 'bara')

process = (ProcessBuilder("Compression Train")
    .add_stream('inlet', feed)
    .add_separator('separator', 'inlet')
    .add_compressor('compressor', 'separator', pressure=100.0)
    .run())

print(f"Compressor power: {process.get('compressor').getPower()/1e6:.2f} MW")

</details> <details> <summary>4. Direct Java Access — full control via jneqsim</summary>

Explicit process management using the Java API — for advanced features see the NeqSim Java repo:

python
from neqsim import jneqsim
from neqsim.thermo import fluid

feed = fluid('srk')
feed.addComponent('methane', 0.9)
feed.addComponent('ethane', 0.1)
feed.setTemperature(30.0, 'C')
feed.setPressure(50.0, 'bara')

# Create equipment using Java classes
inlet = jneqsim.process.equipment.stream.Stream('inlet', feed)
sep = jneqsim.process.equipment.separator.Separator('separator', inlet)
comp = jneqsim.process.equipment.compressor.Compressor('compressor', sep.getGasOutStream())
comp.setOutletPressure(100.0)

# Create and run process explicitly
process = jneqsim.process.processmodel.ProcessSystem()
process.add(inlet)
process.add(sep)
process.add(comp)
process.run()

print(f"Compressor power: {comp.getPower()/1e6:.2f} MW")

</details>

Choosing an Approach

Use Case	Recommended Approach
Learning & prototyping	Python wrappers
Jupyter notebooks	Python wrappers
Production applications	ProcessContext
Multiple parallel processes	ProcessContext
Configuration-driven design	ProcessBuilder
Advanced Java features	Direct Java access

🧪 PVT Simulation

NeqSim includes a pvtsimulation package for common PVT experiments (CCE/CME, CVD, differential liberation, separator tests, swelling, viscosity, etc.) and tuning workflows.

📂 Examples

Explore ready-to-run examples in the examples folder:

Process simulation — processApproaches.py (all four approaches)
Flash calculations, phase envelopes, hydrate prediction
Compressor trains, heat exchangers, separation processes
Jupyter notebooks in examples/jupyter/
Google Colab examples

⚙️ Technical Notes

JPype bridges Python and Java. See the JPype installation guide for platform-specific details. Ensure Python and Java are both 64-bit (or both 32-bit) — mixing architectures will crash on import.

The full list of Python dependencies is on the dependencies page.

🏗️ Contributing

We welcome contributions — bug fixes, new examples, documentation improvements, and more.

CONTRIBUTING.md — Code of conduct and PR process
NeqSim Python Wiki — Guides and usage patterns

📚 Documentation & Resources

Resource	Link
NeqSim homepage	equinor.github.io/neqsimhome
Python wiki	neqsim-python/wiki
JavaDoc API	JavaDoc
Discussion forum	GitHub Discussions
NeqSim Java	equinor/neqsim
MATLAB binding	equinor/neqsimmatlab
Releases	GitHub Releases