ECOS Solver for Java

This library requires JDK 23 as it depends on Java's Foreign Function and Memory (FFM) API.

ecos4j (ECOS Solver for Java) is a Java library that provides an interface from the Java programming language to the native open source mathematical programming solver ECOS. It invokes the solver through Java's Foreign Function and Memory (FFM) API.

Usage

Dependency

Add the latest version from Maven Central to your pom.xml

<dependency>
    <groupId>com.ustermetrics</groupId>
    <artifactId>ecos4j</artifactId>
    <version>x.y.z</version>
</dependency>

Native Library

Either add the latest version of ecos4j-native from Maven Central to your pom.xml

<dependency>
    <groupId>com.ustermetrics</groupId>
    <artifactId>ecos4j-native</artifactId>
    <version>x.y.z</version>
    <scope>runtime</scope>
</dependency>

or install the native solver on the machine and add the location to the java.library.path. ecos4j dynamically loads the native solver.

Run Code

Since ecos4j invokes some restricted methods of the FFM API, use --enable-native-access=com.ustermetrics.ecos4j or --enable-native-access=ALL-UNNAMED (if you are not using the Java Platform Module System) to avoid warnings from the Java runtime.

Build

Java bindings

The directory ./bindings contains the files and scripts needed to generate the Java bindings. The actual bindings are under ./src/main/java in the package com.ustermetrics.ecos4j.bindings.

The scripts depend on the jextract tool, which mechanically generates Java bindings from native library headers.

The bindings are generated in two steps: First, ./bindings/generate_includes.sh generates the dumps of the included symbols in the includes.txt file. Replace absolute platform dependent path with relative platform independent path in the comments. Remove unused includes. Second, ./bindings/generate_bindings.sh generates the actual Java bindings. Add NativeLoader.loadLibrary. Remove platform dependent layout constants and make the code platform independent.

Release

Update the version in the pom.xml, create a tag, and push it by running

export VERSION=X.Y.Z
git checkout --detach HEAD
sed -i -E "s/<version>[0-9]+\-SNAPSHOT<\/version>/<version>$VERSION<\/version>/g" pom.xml
git commit -m "v$VERSION" pom.xml
git tag v$VERSION
git push origin v$VERSION

This will trigger the upload of the package to Maven Central via GitHub Actions.

Then, go to the GitHub repository releases page and update the release.

Credits

This project is based on the native open source mathematical programming solver ECOS, which is developed and maintained by embotech, Alexander Domahidi, and others.