Metadata-Version: 2.4
Name: ovfmi
Version: 0.2.0
Summary: USD-authored FMI co-simulation for ovstage
Author: Omniverse FMI Team
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/NVIDIA-Omniverse/ovfmi
Project-URL: Documentation, https://github.com/NVIDIA-Omniverse/ovfmi#readme
Project-URL: Repository, https://github.com/NVIDIA-Omniverse/ovfmi
Project-URL: Issues, https://github.com/NVIDIA-Omniverse/ovfmi/issues
Keywords: co-simulation,digital-twin,fmi,nvidia,openusd,simulation,ssp,usd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: fmpy==0.3.25
Requires-Dist: numpy>=2.2
Dynamic: license-file

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# ovfmi — FMI/SSP co-simulation for OpenUSD digital twins

Load FMI behavior models from an OpenUSD stage, step them with FMPy, and
synchronize simulation data through a reusable Python API.

*Pre-release. The API and the USD-FMI schema may change between minor versions.*

## What ovfmi does

USD describes world state; FMI and SSP supply simulation behavior. `ovfmi` joins
them through a custom USD schema, so a single USD layer can describe both a scene
and its simulation model in a form that stays readable and composable by USD
tools.

Applications use the Python API to discover `FmuInstance` and `SspInstance`
prims, instantiate their referenced models through FMPy, route values between
model variables and USD attributes, and advance the models.

- Declaratively embed individual FMUs and packaged SSP systems in USD.
- Run FMI 2.0 and FMI 3.0 co-simulation models through the FMPy backend, plus
  SSP 1.0 archives whose internal FMUs meet FMPy's version constraints.
- Map FMI variables to USD attributes, including selected vector components and
  ranges.
- Step deterministically and synchronously, with explicit data routing.

It is aimed at digital-twin, controls and robotics engineers bringing
vendor-neutral FMUs and SSPs into USD-based workflows, and at integrators
assembling standards-based simulation applications.

## Requirements

- Python 3.10 to 3.13, on Linux or Windows.
- FMPy and NumPy, which install with this package.
- An OpenUSD-capable environment for the stage the models are bound to.

The NVIDIA Omniverse libraries — ovstage, ovrtx and ovphysx — are deliberately
not dependencies. They are needed only by the sample application, which ships
with the source rather than in this package.

## Installation

```bash
python -m pip install ovfmi
```

## Quickstart

Import supported symbols directly from `ovfmi`. The package's `__all__` is the
compatibility boundary; submodules and names beginning with an underscore are
implementation details.

```python
from ovfmi import AttributeWrite, FmiHost

with FmiHost() as fmi:
    report = fmi.attach_ovstage(stage, source_asset=usd_path)
    fmi.update_from_ovstage(input_ordinal, input_ordinal)
    fmi.write(
        [
            AttributeWrite(
                prim_paths=("/World/Body",),
                attribute_name="sim:input",
                values=[[1.0]],
            )
        ]
    )
    fmi.step_sync(1.0 / 60.0)

    with fmi.read() as result:
        consume_outputs(result.groups)
```

The public symbols are:

| Symbol | Purpose |
|---|---|
| `FmiHost` | Owns FMI/SSP instances, routing state and simulation lifecycle for one caller-owned ovstage. |
| `FmiHostConfig` | Configures discovery, schema validation, SSP support and missing-input behavior. |
| `MissingInputPolicy` | Selects how unavailable mapped inputs are initialized. |
| `PopulationReport`, `InstanceInfo` | Describe instances created during attachment. |
| `AttributeWrite` | Supplies input values identified by USD prim path and attribute name. |
| `ReadResult`, `ReadGroup` | Provide an owned snapshot of output values in USD space. |

Every public class and method carries detailed docstrings covering ownership,
filtering, operation tokens, ordinals and backend semantics. The present FMPy
backend is synchronous, but `step()` and `write()` still use the
backend-neutral completion-token lifecycle, so an asynchronous backend would not
change calling code.

## Known limitations

Schema discovery needs the original USD file. The currently supported ovstage
release does not expose data authored with unregistered custom schemas, which
includes the USD-FMI `FmuInstance`, `SspInstance`, `FmuConnection` and
`FmuMapping` prims, so instances cannot be discovered from a populated ovstage
alone. `FmiHost.attach_ovstage()` therefore accepts the source file through its
`source_asset` argument and pre-parses it with OpenUSD in an isolated helper
process. Simulation values still flow through the caller-owned ovstage; the
auxiliary parse supplies only the schema description and initial authored
values.

## Standards and references

- [FMI standard](https://fmi-standard.org/)
- [SSP standard](https://ssp-standard.org/)
- [OpenUSD](https://openusd.org/)
- [FMPy](https://github.com/CATIA-Systems/FMPy)

## License

Apache-2.0. Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES.
