{"id":19835095,"url":"https://github.com/equinor/neqsim-native","last_synced_at":"2026-06-12T15:31:53.596Z","repository":{"id":256591527,"uuid":"855822754","full_name":"equinor/neqsim-native","owner":"equinor","description":"NeqSim is a library for calculation of fluid behavior, phase equilibrium and process simulation. This project compiles NeqSim into a native executable or shared library using GraalVM.","archived":false,"fork":false,"pushed_at":"2026-03-01T14:43:34.000Z","size":180418,"stargazers_count":2,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T14:46:40.417Z","etag":null,"topics":["gas","process","simulation"],"latest_commit_sha":null,"homepage":"http://equinor.github.io/neqsimhome/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/equinor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-11T14:11:14.000Z","updated_at":"2026-03-01T14:42:51.000Z","dependencies_parsed_at":"2025-02-28T18:40:40.479Z","dependency_job_id":"8e0e2768-460b-416b-8efa-136c9f18b8a0","html_url":"https://github.com/equinor/neqsim-native","commit_stats":null,"previous_names":["equinor/neqsim-native"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/equinor/neqsim-native","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equinor%2Fneqsim-native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equinor%2Fneqsim-native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equinor%2Fneqsim-native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equinor%2Fneqsim-native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/equinor","download_url":"https://codeload.github.com/equinor/neqsim-native/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/equinor%2Fneqsim-native/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34251774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gas","process","simulation"],"created_at":"2024-11-12T12:06:38.898Z","updated_at":"2026-06-12T15:31:53.590Z","avatar_url":"https://github.com/equinor.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Run Java Tests](https://github.com/equinor/neqsim-native/actions/workflows/verify_build.yml/badge.svg)](https://github.com/equinor/neqsim-native/actions/workflows/verify_build.yml)\n[![Known Vulnerabilities](https://snyk.io/test/github/equinor/neqsim/badge.svg)](https://snyk.io/test/github/equinor/neqsim)\n\n# Neqsim-Native\n\nThe project compiles NeqSim process simulation models into a shared library using GraalVM. This native image can be used directly or integrated into C/C++ programs, making it possible to implement it in process control systems with robust process simulation capabilities.\n\nProcess models can be written in **Java** or **Python** (via GraalPy). Both approaches produce the same kind of native shared library — the caller (C/C++, MATLAB, etc.) cannot tell which language was used. The default build includes Java models only; Python support is available as an opt-in build option.\n\nNeqSim is the main part of the [NeqSim project](https://equinor.github.io/neqsimhome/). NeqSim (Non-Equilibrium Simulator) is a Java library for estimating fluid properties and process design. It is built on a library of fundamental mathematical models related to phase behavior and physical properties of fluids. NeqSim is easily extended with new models. Development was initiated at the [Norwegian University of Science and Technology (NTNU)](https://www.ntnu.edu/employees/even.solbraa).\n\n## Table of Contents\n\n- [Releases](#releases)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Development Environment](#development-environment)\n- [Installation](#installation)\n- [Automated Build Process](#automated-build-process)\n- [Creating a Release](#creating-a-release)\n- [Building Locally](#building-locally)\n- [Adding a New Process Model](#adding-a-new-process-model)\n- [Using the DLL from C/C++](#using-the-dll-from-cc)\n- [Documentation](#documentation)\n- [Unit Testing](#unit-testing)\n- [Project Structure](#project-structure)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Releases\n\nDownload pre-built binaries from the [Releases page](https://github.com/equinor/neqsim-native/releases/).\n\nThe **default** release includes Java process models only (no Python). Python (GraalPy) support can optionally be included at release time.\n\n### Default builds (no Python) — always included\n\n| Platform | Archive |\n|---|---|\n| Linux x86-64 | `neqsim-linux-x64.zip` |\n| Windows x86-64 | `neqsim-windows-x64.zip` |\n| macOS ARM64 | `neqsim-macos-arm64.zip` |\n\n### With Python builds — optional\n\n| Platform | Archive |\n|---|---|\n| Linux x86-64 | `neqsim-linux-x64-python.zip` |\n| Windows x86-64 | `neqsim-windows-x64-python.zip` |\n\n### 32-bit Windows — always included\n\n| Platform | Archive |\n|---|---|\n| Windows x86 (32-bit) | `neqsim-windows-x86.zip` |\n\nThe 32-bit package contains a thin stub DLL that forwards calls over TCP to a 64-bit server EXE. See [stub32/README.md](stub32/README.md) for details.\n\n### Binary size optimization\n\nRelease binaries are compressed with [UPX](https://upx.github.io/) (`--best --lzma`) to reduce download size by ~50%. This is applied automatically by the CI workflow to:\n- 64-bit shared libraries (Linux `.so`, Windows `.dll`)\n\nmacOS `.dylib` files are **not** compressed — UPX does not support Mach-O shared libraries.\n\nThe compressed binaries decompress transparently at load time; no extra steps are needed by the user.\n\n## Use in Visual Studio\n\nSee the [example](example/) folder for sample C++ projects. Needed files:\n\n![Files for compilation](images/files.png)\n\n## 32-bit Windows Support\n\nFor 32-bit applications, a special package is available. It contains a thin 32-bit stub DLL that forwards calls over TCP to a 64-bit server process. The stub exports functions with the same names; however, `calcWaterDewPoint` and `calcWaterInGas` use output-pointer signatures in the stub (see [stub32/neqsim_stub.h](stub32/neqsim_stub.h)).\n\nSee [stub32/README.md](stub32/README.md) for full documentation, usage examples, and build instructions.\n\n## Documentation\n\nMethod documentation and input/output parameters are described in the [API documentation](https://github.com/equinor/neqsim-native/blob/main/doc/README.md).\n\n- **[Java process guide](doc/java-processes.md)** — step-by-step guide for adding Java models\n- **[Python process guide](doc/python-processes.md)** — step-by-step guide for adding Python models\n\n## Unit Testing\n\nUnit testing is done as part of the build process.\nTests can be seen here: https://github.com/equinor/neqsim-native/tree/main/java_graal/src/test/java/neqsim\n\n## Features\n\n- **Native Compilation:** Converts Java-based NeqSim models into native executables or shared libraries.\n- **GraalVM Integration:** Uses GraalVM's `native-image` capabilities for improved performance and reduced startup time.\n- **Python Support (GraalPy):** Write process models in Python using neqsim's Java API via `java.type()` interop — no JVM bridge required.\n- **C/C++ Integration:** Provides native libraries that can be easily integrated into C/C++ projects.\n- **Cross-Platform:** Builds for Linux, Windows, and macOS.\n- **Process Control Applications:** Ideal for embedding simulation models into real-time process control systems.\n\n## Requirements\n\n- **GraalVM JDK 25+** — includes `native-image` (download from [graalvm.org](https://www.graalvm.org/))\n- **Maven** — included via the Maven wrapper (`mvnw` / `mvnw.cmd`)\n- **Git** — for cloning the repository\n- **Visual Studio Build Tools** (Windows only) — for the MSVC toolchain used by `native-image`\n- **build-essential + zlib1g-dev** (Linux only) — C toolchain and compression library for `native-image`\n\n## Development Environment\n\n### GitHub Codespaces / VS Code Dev Containers (recommended)\n\nThe easiest way to get started is to open the repository in a **GitHub Codespace** or a local **VS Code Dev Container**. The devcontainer is pre-configured with GraalVM 25, `native-image`, and the C/C++ toolchain — everything needed to build and test the project.\n\n[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true\u0026repo=equinor/neqsim-native)\n\n\u003e **Important:** The devcontainer is configured to require a machine with **at least 16 GB of RAM** (4-core). GitHub Codespaces will automatically select a qualifying machine type. The default 2-core machine (~6 GB RAM) is not enough for GraalVM native-image compilation — the build will be killed by the OS (exit code 143) during the analysis phase.\n\n**To open locally in VS Code:**\n\n1. Install [Docker](https://www.docker.com/) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)\n2. Open the repository folder in VS Code\n3. When prompted, click **\"Reopen in Container\"** (or run `Dev Containers: Reopen in Container` from the command palette)\n4. The container will build, install GraalVM 25, and run `mvnw verify` automatically\n\nOnce inside the container you can build the native library immediately:\n\n```bash\ncd java_graal\n./mvnw -Pnative-linux-lean package          # default build (Java models only)\n./mvnw -Pnative-linux,with-python package   # with Python support\n```\n\n**To build and run the C++ examples** (builds the native library, compiles the examples, and runs them):\n\n```bash\ncd example/linux\nchmod +x build_and_run.sh\n./build_and_run.sh                # default build\n./build_and_run.sh --with-python  # include Python models\n```\n\nThe devcontainer sets the `NEQSIM_TARGET` environment variable automatically, pointing to `java_graal/target`. You can also compile examples manually using `g++` — see [example/linux/README.md](example/linux/README.md) for details.\n\n## Installation\n\n### 1. Clone the Repository\n\nClone the main neqsim-native repository:\n\n```\ngit clone https://github.com/equinor/neqsim-native.git\n```\n\nNavigate to the java_graal directory which contains the NeqSim process models and build configuration:\n\n```\ncd neqsim-native/java_graal\n```\n\n## Automated Build Process\n\nThis repository includes automated CI/CD workflows via GitHub Actions:\n\n| Workflow | Purpose | Trigger |\n|---|---|---|\n| **Create release (draft)** | Builds default + optional with-python shared libraries for Linux, Windows, and macOS, publishes as draft release | Manual (`workflow_dispatch`) |\n| **Verify Build** | Runs unit tests (Temurin JDK) on Windows + Linux, builds the 32-bit stub DLL | Push / PR to `main` |\n| **Integration Tests** | Runs all tests including `@Tag(\"integration\")` Python model tests | Manual (`workflow_dispatch`) |\n\nBoth workflows use **GraalVM 25.0.1** with the `native-image` component. The Maven build handles everything — there is no need to invoke `native-image` manually.\n\n## Creating a Release\n\nReleases are created via the **\"Multi Platform Release\"** workflow in GitHub Actions.\n\n### Steps\n\n1. Go to **Actions** → **Multi Platform Release** → **Run workflow**\n2. Fill in the inputs:\n\n   | Input | Description |\n   |-------|-------------|\n   | **Release version** | Semantic version, e.g. `2.1.0` — becomes the Git tag `v2.1.0` |\n   | **Include Python (GraalPy) builds?** | Check this box to also produce the with-Python variants (artifact names end in `-python`). Leave unchecked for default-only releases. |\n\n3. Click **Run workflow** and wait for the jobs to finish (~10 min default-only, ~50 min with Python)\n4. Go to **Releases** — a **draft** release has been created with all the zip files attached\n5. Review the draft, edit the release notes if needed, then **Publish**\n\n### What gets built?\n\n| Include Python? | Artifacts produced | Approx. time |\n|:---:|---|---|\n| ☐ Unchecked | 3 default zips (Linux, Windows, macOS) + 1 x86 zip (Windows 32-bit) | ~15 min |\n| ☑ Checked | 3 default + 2 with-python + 1 x86 zips | ~55 min |\n\n### When to include Python\n\n- **Skip Python** (default) for faster, smaller releases. All `PY_*` functions are still exported but return `quality=0` with a clear error message at runtime. This is recommended for most users.\n- **Include Python** when a release specifically needs Python process models (e.g. `PY_run_dewpoint_calculation`). These builds are larger and take longer to compile.\n\n## Building Locally\n\nEnsure [GraalVM JDK 25+](https://www.graalvm.org/) is installed and `JAVA_HOME` points to it.\n\n```bash\ncd java_graal\n\n# Default builds (no Python — recommended):\n./mvnw -Pnative-linux-lean package               # Linux\nmvnw.cmd -Pnative-windows-lean package           # Windows\n./mvnw -Pnative-macos-lean package               # macOS\n\n# With Python support (optional, larger and slower to build):\n./mvnw -Pnative-linux,with-python package        # Linux\nmvnw.cmd -Pnative-windows,with-python package    # Windows\n./mvnw -Pnative-macos,with-python package        # macOS\n```\n\nOutput files appear in `java_graal/target/`:\n\n| File | Description |\n|---|---|\n| `neqsim.dll` / `neqsim.so` / `neqsim.dylib` | Shared library with all exported models |\n| `neqsim.h` | Auto-generated C header with all `@CEntryPoint` functions |\n| `graal_isolate.h` | GraalVM isolate type definitions |\n| `neqsim.lib` | Windows import library (MSVC linker) |\n\n\u003e **Note:** Default builds include Java models only. With-Python builds include both Java and Python models. In default builds, Python functions (`PY_*`) are still exported but return `quality=0` with an error message at runtime.\n\n## Adding a New Process Model\n\nProcess models can be written in **Java** or **Python** (via GraalPy). Both compile into the same shared library.\n\n### Adding a Java Process Model\n\nFor a complete step-by-step guide with full code examples, see **[doc/java-processes.md](doc/java-processes.md)**.\n\n#### Quick checklist\n\n- [ ] **Create the model class** in `java_graal/src/main/java/neqsim/process/\u003cname\u003e/`\n  - Include a `@CEntryPoint` method with `CDoublePointer` / `CIntPointer` output parameters\n  - Use a lock object you `synchronize` on\n- [ ] **Add unit tests** in `java_graal/src/test/java/neqsim/process/\u003cname\u003e/`\n- [ ] **Update `reflect-config.json`** if your model uses reflection-based class loading\n- [ ] **doc/README.md** — API parameter table\n- [ ] *(Optional)* **32-bit stub support** — see [stub32/README.md](stub32/README.md) and update `neqsim_stub.h`, `neqsim_stub.c`, `neqsim_stub.def`, `NeqSimPipeServer.java`, `ProcessDispatcher.java`\n\n### Adding a Python Process Model\n\nPython models require far fewer files — just the `.py` script and a thin Java wrapper (~40 lines). All GraalPy boilerplate is handled by the shared `PythonProcessRunner` class.\n\nSee **[doc/python-processes.md](doc/python-processes.md)** for a complete step-by-step guide with examples.\n\n#### Quick checklist\n\n- [ ] **Python script** in `java_graal/src/main/resources/python/\u003cmodel\u003e.py`\n- [ ] **Java wrapper** in `java_graal/src/main/java/neqsim/process/python/Python\u003cName\u003e.java`\n- [ ] **Unit test** in `java_graal/src/test/java/neqsim/process/python/`\n- [ ] **doc/README.md** — API parameter table\n- [ ] *(Optional)* **32-bit stub support** — see [stub32/README.md](stub32/README.md)\n\n## Using the DLL from C/C++\n\nEvery call follows the same 3-step pattern, regardless of whether the underlying model is Java or Python:\n\n```c\n#include \"neqsim.h\"\n\nint main() {\n    /* 1. Create the GraalVM isolate (once) */\n    graal_isolate_t* isolate = NULL;\n    graal_isolatethread_t* thread = NULL;\n    graal_create_isolate(NULL, \u0026isolate, \u0026thread);\n\n    /* 2. Call any exported function */\n    double dew_point = calcWaterDewPoint(thread, 50.0, 100.0);\n    printf(\"Water dew point: %.2f C\\n\", dew_point);\n\n    /* 3. Tear down the isolate (when done) */\n    graal_tear_down_isolate(thread);\n    return 0;\n}\n```\n\nSee the [example/](example/) folder for complete C++ projects on both Windows and Linux.\n\n## Project Structure\n\n```\nneqsim-native/\n├── .devcontainer/           # Dev Container / Codespaces configuration\n│   ├── devcontainer.json    # GraalVM 25, extensions, post-create command\n│   └── Dockerfile           # Base image with native-image prerequisites\n├── java_graal/              # NeqSim process models and GraalVM build configurations\n│   ├── src/\n│   │   ├── main/java/neqsim/\n│   │   │   ├── process/     # Process models (Java + Python wrappers)\n│   │   │   ├── server/      # IPC server for 32-bit stub\n│   │   │   └── util/        # Utility classes\n│   │   ├── main/resources/\n│   │   │   ├── python/      # Python process models (GraalPy)\n│   │   │   └── META-INF/    # Native-image configuration\n│   │   └── test/            # Unit tests\n│   ├── pom.xml              # Maven configuration (dependencies + native profiles)\n│   └── README.md            # Build documentation\n├── stub32/                  # 32-bit stub DLL + server (for 32-bit applications)\n│   ├── neqsim_stub.c        # Stub DLL source (TCP forwarder)\n│   ├── neqsim_stub.h        # Public API header (drop-in for neqsim.h)\n│   ├── neqsim_stub.def      # DLL export definitions\n│   ├── build.bat            # Build script\n│   └── README.md            # 32-bit architecture documentation\n├── example/                 # C/C++ usage examples (windows + linux)\n├── doc/                     # API parameter documentation + guides\n│   ├── README.md            # Function-level API docs (inputs/outputs)\n│   ├── java-processes.md    # Step-by-step guide for Java models\n│   └── python-processes.md  # Step-by-step guide for Python models\n├── .github/workflows/       # CI/CD workflows\n└── README.md                # This file\n```\n\n## Contributing\n\nContributions to NeqSim Native are welcome! If you have suggestions, bug fixes, or improvements:\n\n1. Fork the repository.\n2. Create a feature branch.\n3. Commit your changes.\n4. Submit a pull request.\n\nFor major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fequinor%2Fneqsim-native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fequinor%2Fneqsim-native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fequinor%2Fneqsim-native/lists"}