fmi-export 0.1.0

FMU export support for FMI 3.0
Documentation

fmi-export

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

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

Quick start: export an FMU

  1. Define a cdylib model crate and derive FmuModel:
use fmi_export::FmuModel;

#[derive(FmuModel, Default, Debug)]
struct MyModel {
    #[variable(causality = Output, start = 1.0)]
    y: f64,
}
  1. Export FMI symbols:
fmi_export::export_fmu!(MyModel);
  1. Bundle the FMU with xtask:
cargo run --package xtask -- --package my-model bundle

Building FMUs

This repository builds FMI 3.0 FMUs from pure Rust code. The FMI API interfacing boilerplate is generated with the FmuModel derive macro. Automated packaging is handled by an xtask module.

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 FMU (this repo)

From the repository root:

cargo run xtask -- --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 run --package xtask -- --package can-triggered-output bundle --release
  • Build for a specific target:
cargo run --package xtask -- --package can-triggered-output bundle --target x86_64-unknown-linux-gnu

FmuModel derive reference

Struct-level attributes

Use #[model(...)] on the struct to configure the generated FMI interfaces and metadata.

#[derive(FmuModel, Default)]
#[model(
    description = "Example FMU",
    model_exchange = true,
    co_simulation = false,
    scheduled_execution = false,
    user_model = true,
)]
struct MyModel {
    #[variable(causality = Output, start = 1.0)]
    y: f64,
}

Supported keys:

  • description: Optional string. Defaults to the struct docstring if omitted.
  • model_exchange: Optional bool. Defaults to true.
  • co_simulation: Optional bool. Defaults to false.
  • scheduled_execution: Optional bool. Defaults to false.
  • user_model: Optional bool. Defaults to true. Set false to provide your own impl UserModel.

Notes:

  • All boolean flags must be explicit (co_simulation = true). Shorthand co_simulation is rejected.
  • #[model()] with no arguments is valid and uses the defaults above.

Field-level attributes

Use #[variable(...)] to include a field as an FMI variable. Use #[alias(...)] for additional aliases. Both attributes accept the same keys.

#[derive(FmuModel, Default)]
struct MyModel {
    /// Height above ground
    #[variable(causality = Output, start = 1.0)]
    h: f64,

    /// Velocity of the ball
    #[variable(causality = Output, start = 0.0)]
    #[alias(name = "der(h)", causality = Local, derivative = h)]
    v: f64,
}

Supported keys for #[variable(...)] and #[alias(...)]:

  • skip: Bool. When true, the field is ignored for FMI variables.
  • name: String. Overrides the variable name (defaults to the field name).
  • description: String. Overrides the field docstring.
  • causality: One of Parameter, CalculatedParameter, Input, Output, Local, Independent, Dependent, StructuralParameter.
  • variability: One of Constant, Fixed, Tunable, Discrete, Continuous.
  • start: Rust expression used as the start value.
  • initial: One of Exact, Calculated, Approx.
  • derivative: Ident referencing another field. Marks this variable as the derivative of that field.
  • event_indicator: Bool. When true, counts toward the FMI event indicator total.
  • interval_variability: One of Constant, Fixed, Tunable, Changing, Countdown, Triggered.
  • clocks: List of clock field idents that this variable belongs to.
  • max_size: Integer. Max size for Binary variables.
  • mime_type: String. MIME type for Binary variables.

Notes:

  • Continuous state variables are inferred by derivative relationships.
  • clocks must reference clock variables in the same model. The generated FMU resolves these to value references.

Child components

Use #[child(...)] to reuse another FmuModel as a component and prefix its variable names.

#[derive(FmuModel, Default)]
struct Parent {
    #[child(prefix = "bus")]
    bus: CanBus,
}

Supported keys:

  • prefix: Optional string. Defaults to the field name. Child variables are named <parent_prefix><prefix>.<child_variable>.

Notes:

  • Child fields should implement the Model trait (typically via FmuModel).
  • #[child] only affects naming and metadata; it does not change runtime behavior of the child component.

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.