FMI4j is a software package for dealing with Functional Mockup Units (FMUs) on the JVM platform
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
library/FMI4j
misc
tools
.gitignore
LICENSE
README.md
_config.yml

README.md

FMI4j

License: MIT contributions welcome

Maven Central

FMI4j is a software package for dealing with Functional Mock-up Units (FMUs) on the Java Virtual Machine (JVM), written in Kotlin.

FMI4j supports FMI 2.0 for Model Exchange and Co-simulation.
For Model Exchange, solvers from Apache Commons Math can be used.

Compared to other FMI libraries targeting the JVM, FMI4j is considerably faster due to the fact that we use JNI with manually optimized C-code instead of JNA or SWIG generated bindings. A significant speedup (2-5x) compared to other FMI implementations for the JVM, such as JFMI and JavaFMI, should be expected.

The package consists of:

Software API

Fmu fmu = Fmu.from(new File("path/to/fmu.fmu")); //URLs are also supported

FmuSlave slave = fmu.asCoSimulationFmu().newInstance();

// Model Exchange is also supported:
//
// Solver solver = ApacheSolvers.euler(1E-3);
// FmuSlave slave = fmu.asModelExchangeFmu(solver).newInstance(); 

slave.init(); //throws on error

double stop = 10;
double stepSize = 1.0/100;
while(slave.getSimulationTime() <= stop) {
    if (!slave.doStep(stepSize)) {
        break;
    }
}
slave.terminate(); //or close, try with resources is also supported

fmu.close() // <- also done automatically by the library if you forget to do it yourself

Gradle plugin

For any FMUs located in your resources/fmus folder, the plugin generates Java code which makes it easier to interact with them progamatically.

Among other things, it generates type safe getter and setters for the FMU variables - grouped by causality. It also generates javadoc based on the information found in the modelDescription.xml.

Example for an FMU named ControlledTemperature given in Kotlin:

ControlledTemperature.newInstance().use { slave -> //try with resources

        slave.init()
        
        //Variables are grouped by causality and have types!
        val tempRef: RealVariable 
                = slave.outputs.temperature_Reference()

        val stop = 10.0
        val stepSize = 1E-2
        while (slave.simulationTime <= stop) {
            
            if (!slave.doStep(stepSize)) {
                break
            }

            tempRef.read(slave).also {
                println("t=${instance.currentTime}, ${tempRef.name}=${it.value}")
            }
            
        }

    }

The plugin has been added to the Gradle Plugin portal.

To use it, simply add the following to your build.gradle

plugins {
    id "no.mechatronics.sfi.fmi4j.FmuPlugin" version "0.5.2"
}

The plugin will automatically add a dependency to the FMI4j artifact fmi-import. It defaults to the implementation configuration. You can change this behaviour through the fmi4j extension. E.g:

fmi4j {
    version = "0.11.1"
    configurationName = "compile"
}

FMU2Jar

FMU2Jar is similar to the Gradle plugin, but it does not require Gradle.

It's a command line application which takes an FMU in and produces a Jar file. You can also tell the application to install the Jar into your local maven repository (.m2), The jar file contains code that makes it easier to work with the FMU progamatically just as the Gradle plugin does.

Running tests

In order to run the tests, a system variable named TEST_FMUs must be present on your system. This variable should point to the location of the content found here.


To get started head over to the Wiki!