Skip to main content

Crate fmi_export

Crate fmi_export 

Source
Expand description

§fmi-export

github crates.io docs.rs build status

A Rust interface to FMUs (Functional Mockup Units) that follow the FMI Standard. This crate provides necessary interfaces and utilities to construct FMUs.

This crate is part of rust-fmi.

See http://www.fmi-standard.org

§Quick start: Build an FMU

  1. Install the cargo-fmi subcommand:
cargo install cargo-fmi
  1. Create a new crate for your model using cargo-fmi:
cargo fmi new my-model

This will generate a cdylib crate with a sample model struct deriving FmuModel:

ⓘ
use fmi_export::FmuModel;

#[derive(FmuModel, Default, Debug)]
struct MyModel {
    #[variable(causality = Output, start = 1.0)]
    y: f64,
}

The export_fmu! macro will generate the required FMI-API exports.

ⓘ
fmi_export::export_fmu!(MyModel);
  1. Build and bundle the FMU with cargo-fmi:
cargo fmi --package my-model bundle

§Building FMUs

This repository builds FMI 3.0 FMUs from pure Rust code, and is driven by the FmuModel derive macro.

The FMI API interfacing boilerplate is generated, and automated packaging is handled by the cargo-fmi subcommand.

§Minimal FMU setup

Your FMU crate must:

  • Be a cdylib:
[lib]
crate-type = ["cdylib"]
  • Derive FmuModel for your model struct
  • Export FMI symbols via export_fmu!

Example skeleton:

ⓘ
use fmi_export::FmuModel;

#[derive(FmuModel, Default, Debug)]
struct MyModel {
    #[variable(causality = Output, start = 1.0)]
    y: f64,
}

fmi_export::export_fmu!(MyModel);

§Build an example FMU (this repo)

From the repository root:

cargo fmi --package can-triggered-output bundle

The FMU zip is written to:

target/fmu/<model_identifier>.fmu

<model_identifier> is the Rust cdylib target name (for can-triggered-output, this is can_triggered_output).

§Common options

  • Build a release FMU:
cargo fmi --package can-triggered-output bundle --release
  • Build for a specific target:
cargo fmi --package can-triggered-output bundle --target x86_64-unknown-linux-gnu

§Building FMUs from Modelica models

Using the rumoca crate, fmi-export can generate Rust code from Modelica models.

The template can be used directly via Rumoca, but the primary workflow is to enable the rumoca feature in fmi-export and call its helper API from build.rs.

§Quick Start

  1. Add fmi-export with the rumoca feature to your Cargo.toml:
[build-dependencies]
fmi-export = { version = "0.1.1", features = ["rumoca"] }
  1. Invoke the Rumoca compiler in your crates’ build.rs:
ⓘ
let model_path = std::path::PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap())
    .join("src/model.mo");
println!("cargo:rerun-if-changed={}", model_path.display());
fmi_export::rumoca::write_modelica_to_out_dir("MyModel", &model_path)
    .expect("render model.mo");

Direct Rumoca usage is also supported (path shown is for this repo checkout):

rumoca model.mo -m MyModel --template-file fmi-export/templates/rust-fmi.jinja > my_fmu_crate/src/lib.rs

If you’re outside this repo, point --template-file at a local copy of rust-fmi.jinja from the fmi-export/templates directory.

See templates/README.md and the examples for further details.

§License

Licensed under either of

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§Feature flags

  • fmi3 (enabled by default) — Enable support for FMI 3.0
  • rumoca — Enable support for Rumoca-based Modelica compilation

Modules§

fmi3
Architecture

Macros§

checked_deref_cs
Safely dereferences an FMI instance pointer for Co-Simulation instances with wrapper context.
checked_deref_me
Safely dereferences an FMI instance pointer for Model Exchange instances.
dispatch_by_instance_type
Dispatches a method call based on the runtime instance_type. This is used for Common trait methods that must work for any instance type (ME/CS/SE).
export_fmu
Main macro for exporting an FMI 3.0 model as a shared library.
generate_getset_functions
Generates getter and setter functions for FMI3 data types.
wrapper_getset_functions

Derive Macros§

FmuModel
FmuModel derive reference