Development Documentation

Guides for developers contributing to NeqSim, extending the library with new models, and integrating with Python.

Overview

This folder contains documentation for:

Getting Started

Document Description
DEVELOPER_SETUP.md Development environment setup
contributing-structure.md Contributing guidelines and code structure
jupyter_development_workflow.md Jupyter notebooks for live Java development

AI-Assisted Task Solving

Document Description
TASK_SOLVING_GUIDE.md Complete workflow for solving tasks with AI while developing the physics engine, including study_config.yaml, intake pauses, document inputs, and deep multi-notebook studies
Solve an Engineering Task Hands-on tutorial: from blank screen to validated report
CODE_PATTERNS.md Copy-paste code starters for every common task type
TASK_LOG.md Persistent memory — searchable log of all solved tasks
LESSONS_LEARNED.md Practical lessons from 45+ solved tasks (EOS, convergence, API gotchas)
image_tools_agents_skills.md Inventory of image-related tools, agents, and skills for P&IDs, drawings, scanned PDFs, maps, and screenshots

Start with CONTEXT.md in the repo root for a 60-second orientation.

For detailed engineering studies, create tasks with explicit depth controls:

neqsim new-task "field development study" --type G --scale comprehensive --report-depth detailed --notebooks 5 --intake-pause always

The generated study_config.yaml controls notebook count and names, supervised NeqSim Runner execution, report sections, benchmark validation, uncertainty/risk requirements, figure minimums, document inputs, and consistency-check gates. Task input can also be provided as markdown prompt files or engineering documents in step1_scope_and_research/references/. The intake pause creates the task folder first, then lets you add or edit input files before notebooks are created. See TASK_SOLVING_GUIDE.md for the full configuration schema and examples.

Extending NeqSim

These guides explain how to add new functionality to NeqSim:

Guide Description
Extending Process Equipment Add custom separators, reactors, and other unit operations
Extending Physical Properties Add custom viscosity, conductivity, and diffusivity models
Extending Thermodynamic Models Add custom equations of state and activity models
Python Extension Patterns Use NeqSim from Python, create wrappers, implement interfaces

Extension Quick Reference

Process Equipment: Extend ProcessEquipmentBaseClass, implement run() method

public class MyEquipment extends ProcessEquipmentBaseClass {
    @Override
    public void run(UUID id) {
        // Get inlet, calculate, set outlet
    }
}

Physical Properties: Extend Viscosity/Conductivity/Diffusivity, implement calcViscosity() etc.

public class MyViscosityModel extends Viscosity {
    @Override
    public double calcViscosity() {
        // Your correlation here
    }
}

Thermodynamic Models: Extend SystemEos, create matching PhaseXxxEos and ComponentXxx

public class SystemMyEos extends SystemEos {
    public SystemMyEos(double T, double P) {
        // Initialize phases with PhaseMyEos
    }
}

Python Integration: Use jneqsim gateway or implement Java interfaces with @JImplements

from neqsim import jneqsim
fluid = jneqsim.thermo.system.SystemSrkEos(300.0, 50.0)

Architecture References

For deeper understanding of NeqSim’s architecture:

Topic Location
Thermodynamic Systems ../thermo/
Process Equipment ../process/
Physical Properties ../physical_properties/
Validation Framework ../integration/ai_validation_framework.md