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.

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.

§Feature flags

  • fmi3 (enabled by default) — Enable support for FMI 3.0

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
Main derive macro for FMU models