Getting Started as a NeqSim Developer

Goal: From git clone to first contribution in 30 minutes.

Step 1: Environment Setup (5 min)

Prerequisites

Required:

Recommended:

Verify Installation:

java -version    # Should show 1.8.0 or higher
git --version    # Should show 2.x or higher

Clone and Build

# Clone repository
git clone https://github.com/equinor/neqsim.git
cd neqsim

# First build (downloads dependencies, ~2 min)
./mvnw clean install

# Verify tests pass
./mvnw test

Windows: Use .\mvnw.cmd instead of ./mvnw

Troubleshooting: See BUILD.md for common issues.

Step 2: Understand Project Structure (10 min)

Read These First (in order)

  1. CONTEXT.md - 60-second repo overview (READ THIS FIRST)
  2. modules.md - Package architecture
  3. This file - Developer-specific workflows

Key Directories

neqsim/
├── src/main/java/neqsim/       # Production code (your changes go here)
│   ├── thermo/                 # Thermodynamics & EOS
│   ├── process/                # Process equipment & flowsheets
│   ├── pvtsimulation/          # PVT lab tests
│   ├── standards/              # Industry standards (ISO, API)
│   └── util/                   # Utilities
│
├── src/test/java/neqsim/       # Unit tests (mirrors main/)
│   ├── thermo/
│   ├── process/
│   └── ...
│
├── src/main/resources/         # Data files, component databases
├── docs/                       # Documentation (markdown)
├── examples/                   # Jupyter notebooks, Java examples
├── .github/agents/             # Copilot Chat agents
├── devtools/                   # Development utilities
└── task_solve/                 # Your local work area (gitignored)

Package Organization

Production code follows domain-driven design:

Package Purpose Key Classes
neqsim.thermo Thermodynamics SystemSrkEos, SystemPrEos, ComponentInterface
neqsim.thermodynamicoperations Flash calculations ThermodynamicOperations, TPflash, PHflash
neqsim.physicalproperties Transport properties Density, viscosity, thermal conductivity
neqsim.process Process equipment Separator, Compressor, HeatExchanger, Pipeline
neqsim.process.processmodel Flowsheets ProcessSystem (the flowsheet orchestrator)
neqsim.pvtsimulation PVT lab tests CME, CVD, DifferentialLiberation
neqsim.standards Industry standards ISO6976, SalesContract, GasQuality

Rule: Tests mirror production structure. If you edit neqsim.process.equipment.separator.Separator, add tests to neqsim.process.equipment.separator.SeparatorTest.

Step 3: Pick Your Path

Choose the contribution type that fits your goal:

A. Fix a Bug or Add a Feature

Best for: Specific issues you’ve encountered or features you need.

  1. Find or create an issue:
    • Browse GitHub Issues
    • Comment “I’ll take this” to claim an issue
    • Or create a new issue describing the bug/feature
  2. Create a branch: 
    git checkout -b fix/issue-123-separator-bug
# or
git checkout -b feature/add-co2-compressor
  3. Make changes:
    • Edit code in src/main/java/neqsim/
    • Follow CODE_PATTERNS.md for examples
    • Add JavaDoc (required for all public methods)
  4. Add tests:
    • Create/update test in src/test/java/neqsim/ (mirror structure)
    • Extend NeqSimTest base class
    • Use descriptive test method names
  5. Verify locally: 
    ./mvnw test -Dtest=YourTest
./mvnw checkstyle:check spotbugs:check pmd:check
  6. Submit PR:

Example PR checklist:

B. Solve an Engineering Task

Best for: Answering engineering questions or developing new capabilities.

NeqSim has an AI-assisted workflow for solving engineering tasks:

Fast Path: Use AI Agent

# In VS Code Copilot Chat:
@solve.task JT cooling for rich gas at 100 bara

The agent creates a task folder, researches the topic, builds a simulation, validates results, and generates a Word report.

Manual Alternative

neqsim new-task "Your task description" --type B --intake-pause always

The intake pause creates the folder first, then lets you edit study_config.yaml, add details to user_input.md, or place document inputs such as PDFs, Excel stream tables, P&IDs, and data sheets in step1_scope_and_research/references/ before notebooks are created. Task notebooks use NeqSim Runner by default, so execution runs in isolated subprocesses with separate JVMs instead of depending on manual kernel restarts. Runner outputs are merged into task-level results.json, and the report gate warns if planned notebook jobs are missing, failed, or timed out.

Then follow the workflow in task_solve/<your_task>/README.md:

After completing:

See: TASK_SOLVING_GUIDE.md for complete workflow.

C. Write Documentation

Best for: Filling gaps, fixing errors, or improving clarity.

  1. Find documentation to improve:
  2. Use AI assistance (optional): 
    @documentation Create a guide for TEG dehydration calculations
  3. Follow conventions:
    • Add Jekyll YAML front matter to all markdown files: 
      ---
title: Your Document Title
description: Brief description with searchable keywords
---
    • Use proper markdown formatting (see documentation agent)
    • Add KaTeX for equations: $...$ for inline, $$...$$ for display
    • Create links to other docs: [text](relative/path.md)
  4. Update indexes:
  5. Verify links: 
    # Check for broken links
python docs/check_links.py

Example documentation PR:

D. Add Examples

Best for: Demonstrating capabilities to help others learn.

Jupyter Notebooks

  1. Create notebook:
    • Use AI agent: @notebook.example 3-stage compression with intercooling
    • Or manually create in examples/notebooks/
  2. Follow structure:
    • Introduction cell (what it demonstrates)
    • Setup cell (imports workspace Java classes using neqsim_dev_setup)
    • Fluid creation
    • Process building
    • Run simulation
    • Results (formatted table/plots)
    • Discussion/conclusions
  3. Import pattern for repository/task notebooks (CRITICAL): 
    import os
import sys
from pathlib import Path

PROJECT_ROOT = Path(os.environ.get("NEQSIM_PROJECT_ROOT", Path.cwd())).resolve()
for candidate in [PROJECT_ROOT] + list(PROJECT_ROOT.parents):
    if (candidate / "pom.xml").exists() and (candidate / "devtools" / "neqsim_dev_setup.py").exists():
        PROJECT_ROOT = candidate
        break
sys.path.insert(0, str(PROJECT_ROOT / "devtools"))

from neqsim_dev_setup import neqsim_init, neqsim_classes

ns = neqsim_init(project_root=PROJECT_ROOT, recompile=False, verbose=True)
ns = neqsim_classes(ns)

SystemSrkEos = ns.SystemSrkEos
ProcessSystem = ns.ProcessSystem
Stream = ns.Stream

    This is different from published pip quickstarts: local repository notebooks should not use from neqsim import jneqsim because that can miss workspace Java changes.

  4. Test notebook:
    • Restart kernel & run all cells
    • Verify runtime < 5 minutes (or mark as “long-running”)
  5. Add to index:
    • Update examples/README.md
    • Add brief description

Java Examples

  1. Create standalone example in examples/neqsim/
  2. Make it self-contained: Include all required code
  3. Add comments: Explain each step
  4. Test compilation: javac YourExample.java

See: notebook.example.agent.md for guidelines.

E. Contribute a Skill

Skills are the easiest way to contribute — no Java required. You write a markdown file with domain knowledge, code patterns, and common mistakes that AI agents use to solve engineering tasks.

Core skill (shipped with NeqSim):

neqsim new-skill "my-topic"      # scaffold SKILL.md
# Edit .github/skills/neqsim-my-topic/SKILL.md
# Register in README + copilot-instructions.md
# Submit PR

Community skill (hosted in your own repo):

# 1. Create SKILL.md in your GitHub repo
# 2. Publish to the catalog:
neqsim skill publish your-username/your-repo

See: Skills Guide for the full walkthrough including SKILL.md format, requirements checklist, and private/team skills.

Step 4: Code Style and Validation

Automatic Formatting (VS Code)

If you followed the setup in CONTRIBUTING.md, code formats automatically on save.

Manual format:

Before Committing

Run these checks locally:

# 1. Compile
./mvnw compile

# 2. Run tests
./mvnw test

# 3. Static analysis
./mvnw checkstyle:check spotbugs:check pmd:check

# 4. If you modified docs, regenerate manual
cd docs
python generate_manual.py

Fix any issues before pushing. CI runs the same checks.

Java 8 Compatibility (CRITICAL)

All code MUST compile with Java 8. Never use:

See copilot-instructions.md for complete list.

Step 5: Submit Your Contribution

Create Pull Request

  1. Push your branch: 
    git push -u origin your-branch-name
  2. Create PR (choose one):
    • GitHub UI: Go to repo → Pull Requests → New pull request
    • GitHub CLI: gh pr create
  3. Fill the template:
    • What changed (concise summary)
    • Why (link to issue if applicable)
    • Testing performed
    • Docs updated (checkbox)
    • Breaking changes (checkbox)
  4. Wait for CI checks:
    • Build must pass
    • All tests must pass (100%)
    • Static analysis must pass
  5. Respond to reviews:
    • Address comments
    • Push new commits (CI re-runs automatically)
  6. Merge:
    • After approval, maintainer merges (usually squash & merge)

PR Best Practices

✅ DO:

❌ DON’T:

Common Workflows

Update Your Branch with Latest Master

# Fetch latest changes
git fetch origin

# Rebase on master (recommended)
git rebase origin/master

# Or merge (alternative)
git merge origin/master

If conflicts: Resolve manually, then:

git rebase --continue    # If rebasing
# or
git commit               # If merging

Run Specific Test

# Single test class
./mvnw test -Dtest=SeparatorTest

# Single test method
./mvnw test -Dtest=SeparatorTest#testTwoPhase

# All tests in a package
./mvnw test -Dtest=neqsim.thermo.**

Debug in IDE

VS Code

IntelliJ IDEA

Eclipse

Build Workspace Classes for Notebooks

After Java changes, compile the workspace and use the devtools notebook setup. Do not copy a JAR into the Python neqsim package for repository notebooks.

# Windows
.\mvnw.cmd compile

# Restart Jupyter kernel or let NeqSim Runner start a fresh worker JVM

Clean Workspace

# Remove all generated files
./mvnw clean

# Remove IDE metadata (if needed)
rm -rf .vscode .idea .project .classpath

# Regenerate IDE files
./mvnw eclipse:eclipse    # Eclipse
# For VS Code/IntelliJ, just re-import as Maven project

Getting Help

Documentation

Community

Internal Resources (Equinor)

Next Steps

Once you’re comfortable with the basics:

Deepen Understanding

Advanced Topics

Contribute to the Project

Quick Reference Card

Essential Commands

# Build
./mvnw clean install

# Test
./mvnw test -Dtest=ClassName#methodName

# Format check
./mvnw checkstyle:check

# Create task
neqsim new-task "Task description" --intake-pause always

# Update branch
git fetch origin && git rebase origin/master

File Locations

Key Files

Ready to contribute? Pick a path above and dive in! 🚀