Frequently Asked Questions (FAQ)

Table of Contents

General

What is NeqSim?

NeqSim (Non-Equilibrium Simulator) is a Java library for thermodynamic calculations and process simulation, specializing in oil and gas applications. It provides:

Where can I find the API documentation?

The full JavaDoc is available at https://htmlpreview.github.io/?https://github.com/equinor/neqsimhome/blob/master/javadoc/site/apidocs/index.html.

Is NeqSim open source?

Yes, NeqSim is open source under the Apache 2.0 license. You can freely use, modify, and distribute it.

Who maintains NeqSim?

The project is developed by Equinor with contributions from the community. Contact Even Solbraa (esolbraa@gmail.com) for questions.

What Java version is required?

NeqSim requires Java 8 or higher. Java 11+ is recommended for best performance.

Installation & Setup

How do I add NeqSim to my project?

Maven:

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

Gradle:

implementation 'com.equinor.neqsim:neqsim:3.0.0'

Direct Download: Download the shaded JAR from GitHub releases.

How do I build NeqSim from source?

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

On Windows, use mvnw.cmd install.

How do I run the tests?

After cloning the repository, execute:

./mvnw test

To run a specific test:

./mvnw test -Dtest=YourTestClassName

Thermodynamics

Which equation of state should I use?

Application Recommended EOS
General natural gas SystemSrkEos
Reservoir/PVT SystemPrEos
Water + hydrocarbons SystemSrkCPAstatoil
Glycol dehydration SystemSrkCPAstatoil
High-accuracy natural gas SystemGERG2008Eos
CO2 capture/CCS SystemSrkCPAstatoil or SystemSpanWagnerEos
Electrolytes/brine SystemElectrolyteCPAstatoil

How do I set up a mixing rule?

// For SRK/PR - use classic van der Waals mixing rule
system.setMixingRule("classic");  // or system.setMixingRule(2);

// For CPA - use CPA mixing rule
system.setMixingRule(10);

// For advanced mixing (Huron-Vidal with NRTL)
system.setMixingRule("HV", "NRTL");

Why does my flash calculation not converge?

Common causes and solutions:

  1. Near critical conditions: Reduce step size or try different initial conditions
  2. Very heavy fractions: Check that TBP characterization is correct
  3. Extreme T/P conditions: Verify values are within model validity range
  4. Missing components: Ensure all components have database parameters

How do I calculate a phase envelope?

ThermodynamicOperations ops = new ThermodynamicOperations(system);
ops.calcPTphaseEnvelope();

double[] cricondenbar = ops.get("cricondenbar");
double[] cricondentherm = ops.get("cricondentherm");

How do I handle plus fractions?

// Add plus fraction with average properties
system.addPlusFraction("C10+", 10.0, 0.200, 820.0);

// Set characterization model
system.getCharacterization().setTBPModel("PedersenSRK");
system.getCharacterization().setPlusFractionModel("Pedersen");
system.getCharacterization().characterisePlusFraction();

Process Simulation

How do I create a simple process?

ProcessSystem process = new ProcessSystem();

// Add feed stream
Stream feed = new Stream("Feed", fluid);
process.add(feed);

// Add equipment
Separator sep = new Separator("Sep", feed);
process.add(sep);

// Run
process.run();

Equipment names must be unique - why?

ProcessSystem uses equipment names as identifiers. Use unique names:

Separator sep1 = new Separator("HP Separator", stream1);
Separator sep2 = new Separator("LP Separator", stream2);  // Different name

How do I implement a recycle?

Recycle recycle = new Recycle("Recycle");
recycle.addStream(separator.getLiquidOutStream());
recycle.setTolerance(1e-6);
process.add(recycle);

// Connect output to upstream mixer
mixer.addStream(recycle.getOutletStream());

How do I set compressor efficiency?

// Isentropic efficiency
compressor.setIsentropicEfficiency(0.75);
compressor.setUsePolytropicCalc(false);

// OR polytropic efficiency
compressor.setPolytropicEfficiency(0.80);
compressor.setUsePolytropicCalc(true);

Physical Properties

How do I get viscosity?

// After running flash
ops.TPflash();

// Gas viscosity
double gasVisc = system.getPhase("gas").getViscosity("cP");

// Liquid viscosity
double liqVisc = system.getPhase("oil").getViscosity("cP");

What viscosity models are available?

See Viscosity Models for details.

How do I get the speed of sound?

double soundSpeed = system.getPhase("gas").getSoundSpeed();  // m/s

How do I get interfacial tension?

double ift = system.getInterfacialTension(0, 1);  // Phase indices

Troubleshooting

NullPointerException after creating system

Always run flash before accessing properties:

ThermodynamicOperations ops = new ThermodynamicOperations(system);
ops.TPflash();  // REQUIRED before accessing properties

“Component not found” error

Check component name spelling. Use exact names from the database:

// Correct
system.addComponent("methane", 1.0);
system.addComponent("n-butane", 1.0);  // Note: n-butane, not nbutane

// Find available components
// Check database or use system.getComponentNames()

Very slow calculations

  1. Reduce number of pseudo-components in characterization
  2. Use simpler EOS (SRK instead of CPA) if polar components not critical
  3. Reduce number of calculation increments in pipelines
  4. Check for convergence issues causing many iterations

Process doesn’t converge

  1. Check for reasonable initial conditions
  2. Verify equipment is connected properly
  3. For recycles, provide good initial guess and check tolerance
  4. Try running units individually to isolate issue

Contributing

How do I contribute to NeqSim?

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Run ./mvnw verify to check code style
  5. Submit a pull request

See Contributing Structure for details.

How do I report a bug?

Open an issue at https://github.com/equinor/neqsim/issues with:

Where can I ask questions?