Python interface to the NeqSim engine — fluid properties, process simulation, and PVT analysis from Python and Jupyter notebooks.
Quick Start · Process Simulation · PVT Simulation · Examples · Docs · Community
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 |
| pip (requires Java 17+) | conda (Java included) |
pip install neqsim | conda install -c conda-forge neqsim |
Prerequisites: Python 3.10+ and Java 17+ (NeqSim 3.15+ requires Java 17 or higher; earlier NeqSim releases required Java 11+). The conda package automatically installs OpenJDK — no separate Java setup needed. For pip, install Java from Adoptium.
fromneqsim.thermoimportfluid, TPflash, printFrame# Create a natural gas fluidfl=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}")NeqSim Python provides multiple ways to build process simulations:
1. Python Wrappers — recommended for beginners & notebooks
Simple functions with a global process — great for prototyping:
fromneqsim.thermoimportfluidfromneqsim.processimportstream, compressor, separator, runProcess, clearProcessclearProcess()
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")2. ProcessContext — recommended for production code
Context manager with explicit process control — supports multiple independent processes:
fromneqsim.thermoimportfluidfromneqsim.processimportProcessContextfeed=fluid('srk')
feed.addComponent('methane', 0.9)
feed.addComponent('ethane', 0.1)
feed.setTemperature(30.0, 'C')
feed.setPressure(50.0, 'bara')
withProcessContext("Compression Train") asctx:
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")3. ProcessBuilder — fluent API for configuration-driven design
Chainable builder pattern:
fromneqsim.thermoimportfluidfromneqsim.processimportProcessBuilderfeed=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")4. Direct Java Access — full control via jneqsim
Explicit process management using the Java API — for advanced features see the NeqSim Java repo:
fromneqsimimportjneqsimfromneqsim.thermoimportfluidfeed=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 classesinlet=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 explicitlyprocess=jneqsim.process.processmodel.ProcessSystem()
process.add(inlet)
process.add(sep)
process.add(comp)
process.run()
print(f"Compressor power: {comp.getPower()/1e6:.2f} MW")| 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 |
The
jneqsimgateway is the first-class path for the long tail. Only a curated subset of NeqSim's ~2500 Java classes has hand-written Python wrappers. Mechanical design, safety, field development, automation, and most specialized equipment are used directly throughjneqsim— no wrapper needed.
Direct jneqsim access is powerful but hard to explore (a JPackage has no
autocomplete). The neqsim.discovery module scans the API at runtime so you can
list, search, and inspect every class from Python:
fromneqsimimportdiscoverydiscovery.list_equipment() # every process-equipment classdiscovery.list_packages('process') # sub-packages of neqsim.processdiscovery.find_classes('scrubber') # search the whole API by keywordprint(discovery.describe('Compressor')) # constructors + methods via reflectionCompressor=discovery.get_class('Compressor') # JClass by simple or full nameFor IDE autocomplete and type checking across the entire Java API, generate type
stubs (already packaged as jneqsim-stubs, regenerate with
python scripts/generate_stubs.py) and point your editor at src. An offline
API manifest (python scripts/generate_api_manifest.py) lets discovery list,
search, and describe classes instantly and JVM-free.
With pip install "neqsim[schema]" you can build flowsheets from typed
pydantic models — autocomplete and validation
before the JVM runs:
fromneqsim.process.schemaimportProcessModel, Fluid, Unitmodel=ProcessModel(
fluid=Fluid(eos="srk", components={"methane": 0.9, "ethane": 0.1}),
process=[
Unit(type="Stream", name="feed",
properties={"flowRate": [50000.0, "kg/hr"], "pressure": [50.0, "bara"]}),
Unit(type="Separator", name="HP Sep", inlet="feed"),
],
)
result=model.run() # validates, builds, and runsfromneqsim.thermo.componentsimportfind_components, suggest_componentfind_components("glycol") # search the component databasesuggest_component("methan") # ['methane', 'methanol', ...] — catch typosStreams and processes render as HTML tables in notebooks automatically (just display the object) — no extra call needed.
One helper turns any process into a tidy stream table (works for every equipment type, because it walks the flowsheet's streams):
fromneqsim.processimportstream_table, equipment_table, runProcessrunProcess()
stream_table() # one row per stream: flow, T, P, phases, density, molar massequipment_table() # one row per unit: name, type, inlet/outlet countsstream_table(my_process) # or pass an explicit ProcessSystem / ProcessContextNeqSim includes a pvtsimulation package for common PVT experiments (CCE/CME, CVD, differential liberation, separator tests, swelling, viscosity, etc.) and tuning workflows.
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
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.
By default, import neqsim starts the JVM immediately. This can be tuned via environment variables:
| Variable | Default | Purpose |
|---|---|---|
NEQSIM_JVM_AUTOSTART | 1 | Set to 0/false/no to disable automatic JVM startup on import. Call init_jvm() explicitly before using jneqsim. |
NEQSIM_JVM_ARGS | (none) | Extra JVM startup arguments (space separated), appended after the default -Xrs. |
NEQSIM_JVM_MAX_HEAP | (none) | Max JVM heap size, e.g. 2g — passed as -Xmx2g. |
importosos.environ["NEQSIM_JVM_AUTOSTART"] ="0"# must be set before `import neqsim`fromneqsim.neqsimpythonimportinit_jvm, is_jvm_startedprint(is_jvm_started()) # Falseinit_jvm(jvm_args=["-Xrs"]) # start explicitly, e.g. with custom argsprint(is_jvm_started()) # Trueinit_jvm() is safe to call multiple times — it is a no-op if the JVM is already running.
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
| 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 |
NeqSim uses SemVer for versioning.
Even Solbraa (esolbraa@gmail.com), Marlene Louise Lund
NeqSim development was initiated at NTNU. A number of master and PhD students have contributed — we greatly acknowledge their contributions.