Metadata-Version: 2.3
Name: mdreader
Version: 0.3.0
Summary: A Python library for reading and parsing Functional Mock-up Interface model description XML file.
Author: coder
Author-email: coder <coder@timeintegral.ai>
License: 
         The MIT License (MIT)
         
         Copyright (c) 2025 timeintegral.ai
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in
         all copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
         THE SOFTWARE.
Requires-Dist: pydantic>=2.11.5,<3.0.0
Requires-Python: >=3.11
Project-URL: Repository, https://github.com/time-integral/mdreader
Description-Content-Type: text/markdown

# mdreader 📖

A Python library for reading and parsing Functional Mock-up Interface (FMI 2.0 and 3.0) model description XML files into Pydantic models.

[![PyPI version](https://badge.fury.io/py/mdreader.svg)](https://badge.fury.io/py/mdreader)

## Installation 📦

Add `mdreader` to your `pyproject.toml` with `uv` with:

``` bash
uv add mdreader
```

> To install `uv`, see https://docs.astral.sh/uv/getting-started/installation/

## How to use 🚀

To read and parse an FMI model description (works for both 2.0 and 3.0):

```python
import mdreader.fmi2 as fmi2
import mdreader.fmi3 as fmi3

# Read from XML file
md = fmi2.read_model_description("path/to/fmi2/modelDescription.xml")  # or fmi3.read_model_description for 3.0
# Read from FMU archive
md = fmi2.read_model_description("path/to/model.fmu")  # or fmi3.read_model_description for 3.0

# Read from unzipped FMU directory
md = fmi2.read_model_description("path/to/unzipped/fmu/directory")  # or fmi3.read_model_description for 3.0

print(md)
```

## Features ✨

- Parse FMI 2.0 and 3.0 model description XML files
- Read model information from FMU archives
- Access model metadata (name, version, author, GUID, etc.)
- Extract variable definitions (real, integer, boolean, string, enumeration, clock, binary)
- Access unit definitions and type definitions
- Support for Model Exchange, Co-Simulation, and Scheduled Execution interfaces
- Parse model structure, dependencies, and experiment configurations
- Full support for FMI 3.0 features including structural parameters, clock variables, and directional derivatives

## Why another FMI model description reader? 🤔

* **Lightweight**: mdreader only depends on Pydantic
* **De/Serialization**: Pydantic models support easy serialization to/from JSON, dict, etc.
* **Validation**: mdreader uses Pydantic models to ensure the integrity of the parsed data
* **FMI version specific**: The `fmi2.FMIModelDescription` and `fmi3.FMIModelDescription` classes are specific to their respective FMI versions (not a mix of versions), making it simpler to use for each version

## Related projects 🔗

* [fmpy](https://github.com/CATIA-Systems/FMPy): A similar `read_model_description` function is available in FMPy, but it uses custom classes instead of Pydantic models and has more dependencies.

## Licensing 📄

The code in this project is licensed under MIT license.
See the [LICENSE](LICENSE) file for details.
