Getting Started with NeqSim

Use this page as a launchpad into the NeqSim documentation. It mirrors the high-level structure from the Colab introduction notebook and links directly to reference guides and examples.

Table of Contents

Quick Start

Add NeqSim as a dependency in your pom.xml:

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

Direct JAR Download

Download the shaded JAR from the releases page and add to your classpath.

Set up NeqSim locally

Clone the repository and build with the Maven wrapper:

git clone https://github.com/equinor/neqsim.git
cd neqsim
./mvnw install

On Windows:

mvnw.cmd install

The command downloads dependencies, compiles the project, and runs the test suite. For environment notes and troubleshooting tips, see the README and developer setup guide.

Requirements

Your First Calculation

Simple Flash Calculation

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

public class FirstCalculation {
    public static void main(String[] args) {
        // 1. Create a natural gas system at 25°C and 50 bar
        SystemSrkEos gas = new SystemSrkEos(298.15, 50.0);
        gas.addComponent("methane", 0.90);
        gas.addComponent("ethane", 0.06);
        gas.addComponent("propane", 0.03);
        gas.addComponent("n-butane", 0.01);
        gas.setMixingRule("classic");

        // 2. Perform flash calculation
        ThermodynamicOperations ops = new ThermodynamicOperations(gas);
        ops.TPflash();

        // 3. Initialize properties — REQUIRED before reading physical properties.
        // TPflash only solves phase equilibrium (compositions, phase fractions).
        // Physical and transport properties (density, viscosity, thermal conductivity)
        // are NOT calculated automatically by TPflash — this is by design to improve
        // performance, since many workflows only need equilibrium results.
        // Call initProperties() to compute both thermodynamic and transport properties.
        gas.initProperties();

        // 4. Print results
        System.out.println("Number of phases: " + gas.getNumberOfPhases());
        System.out.println("Density: " + gas.getDensity("kg/m3") + " kg/m³");
        System.out.println("Z-factor: " + gas.getPhase("gas").getZ());
        System.out.println("Molecular weight: " + gas.getMolarMass() * 1000 + " g/mol");
    }
}

Simple Process Simulation

import neqsim.process.equipment.stream.Stream;
import neqsim.process.equipment.valve.ThrottlingValve;
import neqsim.process.equipment.separator.Separator;
import neqsim.process.processmodel.ProcessSystem;
import neqsim.thermo.system.SystemSrkEos;

public class FirstProcess {
    public static void main(String[] args) {
        // 1. Create fluid
        SystemSrkEos fluid = new SystemSrkEos(320.0, 100.0);
        fluid.addComponent("methane", 0.80);
        fluid.addComponent("ethane", 0.10);
        fluid.addComponent("propane", 0.05);
        fluid.addComponent("n-pentane", 0.05);
        fluid.setMixingRule("classic");

        // 2. Create stream
        Stream feed = new Stream("Feed", fluid);
        feed.setFlowRate(10000.0, "kg/hr");
        feed.setTemperature(50.0, "C");
        feed.setPressure(100.0, "bara");

        // 3. Add equipment
        ThrottlingValve valve = new ThrottlingValve("Valve", feed);
        valve.setOutletPressure(20.0, "bara");

        Separator separator = new Separator("Separator", valve.getOutletStream());

        // 4. Build and run process
        ProcessSystem process = new ProcessSystem();
        process.add(feed);
        process.add(valve);
        process.add(separator);

        // Use runOptimized() for best performance (auto-selects strategy)
        process.runOptimized();

        // 5. Results
        System.out.println("Gas rate: " + separator.getGasOutStream().getFlowRate("kg/hr") + " kg/hr");
        System.out.println("Liquid rate: " + separator.getLiquidOutStream().getFlowRate("kg/hr") + " kg/hr");
    }
}

Execution Strategies

NeqSim provides optimized execution strategies for complex process simulations:

Method Best For Speedup
run() Simple processes baseline
runOptimized() Recommended 28-40%
runParallel() Feed-forward (no recycles) 40-57%
runHybrid() Complex recycle processes 38% 
// Recommended - auto-selects best strategy based on process topology
process.runOptimized();

// Analyze process structure
System.out.println(process.getExecutionPartitionInfo());

See ProcessSystem documentation for details.

Fundamentals and thermodynamics

Equations of State

NeqSim supports multiple equations of state for different applications:

EOS Class Best For
SRK SystemSrkEos General hydrocarbon systems
Peng-Robinson SystemPrEos Reservoir/liquid density
SRK-CPA SystemSrkCPAstatoil Water, glycols, alcohols
GERG-2008 SystemGERG2008Eos Natural gas custody transfer

Fluid characterization and PVT workflows

Heavy Fraction Handling

For oils with C7+ fractions:

SystemSrkEos oil = new SystemSrkEos(350.0, 100.0);
oil.addComponent("methane", 10.0);
oil.addComponent("ethane", 5.0);
// ... light components ...

// Add TBP fractions
oil.addTBPfraction("C7", 5.0, 0.092, 730.0);
oil.addTBPfraction("C8", 4.0, 0.104, 750.0);
oil.addPlusFraction("C10+", 20.0, 0.200, 820.0);

// Characterize
oil.getCharacterization().setTBPModel("PedersenSRK");
oil.getCharacterization().characterisePlusFraction();

Process simulation

Available Equipment

NeqSim includes 50+ unit operations:

Category Equipment
Separation Separator, ThreePhaseSeparator, DistillationColumn, MembraneSeparator
Compression Compressor, Pump, Expander, Ejector
Heat Transfer Heater, Cooler, HeatExchanger
Flow Control ThrottlingValve, FlowRateController
Pipelines PipeBeggsAndBrills, AdiabaticPipe, WaterHammerPipe
Specialty Electrolyzer, WindTurbine, SolarPanel, Battery

Pipeline and multiphase flow

Pipeline Models

PipeBeggsAndBrills pipeline = new PipeBeggsAndBrills("Pipeline", inletStream);
pipeline.setLength(10000.0);           // 10 km
pipeline.setDiameter(0.2);             // 8 inch
pipeline.setElevation(50.0);           // 50m elevation gain
pipeline.setPipeWallRoughness(4.5e-5); // Steel
pipeline.run();

Dynamic behavior and process safety

Safety Systems

NeqSim provides comprehensive safety simulation:

// PSV sizing example
ValveController psv = new ValveController("PSV-001");
psv.setMaxPressure(50.0, "bara");
psv.setReliefPressure(55.0, "bara");

Unit operations and equipment models

Equipment Categories

Integration, control, and automation

PID Control Example

ControllerDeviceBaseClass controller = new ControllerDeviceBaseClass();
controller.setControllerSetPoint(50.0);
controller.setControllerParameters(0.5, 100.0, 0.0); // Kp, Ti, Td
valve.setController(controller);

Examples and tutorials

Jupyter Notebooks

GitHub Pages publishes the rendered tutorial pages, while the source notebooks remain available on GitHub and can be opened directly in Google Colab.

External Resources