motulator-export 0.7.0__tar.gz

motulator_export-0.7.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled files
+__pycache__/
+*.pyc
+
+# Distribution
+*.egg-info/
+build/
+dist/
+
+# Environments
+.venv
+
+# PLECS autosave files and temporary models of the comparison scripts
+*.autosave
+*_tmp.plecs
+
+# Simulink models, compiled S-functions, and caches built by the generated scripts
+examples/simulink/*.slx
+*.mex*
+*.slxc
+slprj/
+
+# Sphinx documentation (the build, the API reference, and the gallery)
+docs/build/
+docs/source/autoapi/
+docs/source/examples/
+docs/source/sg_execution_times.rst
+
+# macOS specific
+.DS_Store

motulator_export-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aalto Electric Drives
+
+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.

motulator_export-0.7.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: motulator-export
+Version: 0.7.0
+Summary: Export motulator drive and grid converter systems to PLECS and Simulink, and simulate them natively
+Project-URL: Homepage, https://github.com/Aalto-Electric-Drives/motulator-export
+Project-URL: Documentation, https://aalto-electric-drives.github.io/motulator-export/
+Project-URL: motulator, https://github.com/Aalto-Electric-Drives/motulator
+Author-email: Marko Hinkkanen <marko.hinkkanen@aalto.fi>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: PLECS,Simulink,control,converter,motor,simulation
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python
+Requires-Python: >=3.12
+Requires-Dist: motulator<0.16,>=0.15.2
+Requires-Dist: numpy
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: pip-audit; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: doc
+Requires-Dist: myst-parser; extra == 'doc'
+Requires-Dist: numpydoc; extra == 'doc'
+Requires-Dist: sphinx; extra == 'doc'
+Requires-Dist: sphinx-autoapi; extra == 'doc'
+Requires-Dist: sphinx-book-theme; extra == 'doc'
+Requires-Dist: sphinx-copybutton; extra == 'doc'
+Requires-Dist: sphinx-gallery; extra == 'doc'
+Description-Content-Type: text/markdown
+
+# motulator-export
+
+Export [*motulator*](https://github.com/Aalto-Electric-Drives/motulator) drive systems and grid converter systems to [PLECS](https://www.plexim.com/products/plecs) and [Simulink](https://www.mathworks.com/products/simulink.html), and simulate them natively in C.
+
+**Documentation:** https://aalto-electric-drives.github.io/motulator-export/
+
+Build the system in *motulator* as usual, then:
+
+```python
+from motulator_export import native, plecs, simulink
+
+plecs.write_model("drive.plecs", mdl, ctrl, t_stop=1.2)  # PLECS model
+simulink.write_model("drive.slx", mdl, ctrl, t_stop=1.2)  # Simulink model
+res = native.Simulation(mdl, ctrl).simulate(t_stop=1.2)  # Native simulation
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aalto-Electric-Drives/motulator-export/main/docs/source/images/plecs_drive_black.png">
+  <img alt="PLECS model of a 2.2-kW IPMSM drive" src="https://raw.githubusercontent.com/Aalto-Electric-Drives/motulator-export/main/docs/source/images/plecs_drive.png">
+</picture>
+
+*PLECS model of a 2.2-kW IPMSM drive with sensorless flux-vector control, written by [examples/ipmsm_2kw_fvc.py](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/examples/ipmsm_2kw_fvc.py).*
+
+- **One control code everywhere.** The control algorithms of *motulator* are ported to C. The same code runs in PLECS, in Simulink, and in the native simulation.
+- **The structure of *motulator*.** Each class of the control system is a masked block with the arguments of its class, nested as in *motulator*. The parameters are set as in a *motulator* script, and they can be changed without Python.
+- **Verified.** The PLECS and Simulink models agree with *motulator* to about 1e-6 relative to the signal magnitudes, and the native simulation to the rounding errors.
+- **Fast.** The native simulation is 30 to 40 times faster than *motulator*, which is useful, e.g., for parameter sweeps.
+
+## Installation
+
+Python 3.12 or later. Install the package in a virtual environment, which also installs *motulator* 0.15.2 or a later 0.15 release:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+python -m pip install motulator-export
+```
+
+The examples are in the repository. To run them, clone the repository and install the package from it:
+
+```bash
+git clone https://github.com/Aalto-Electric-Drives/motulator-export
+cd motulator-export
+python -m pip install -e .
+python examples/ipmsm_2kw_fvc.py
+```
+
+Then open the model `examples/ipmsm_2kw_fvc.plecs` in PLECS. See the [documentation](https://aalto-electric-drives.github.io/motulator-export/guide/getting_started.html) for the requirements of PLECS, Simulink, and the native simulation.
+
+## Development
+
+Install the package with `pip install -e .[dev]` and run the tests with `pytest` (requires gcc). The implementation is described in the developer notes:
+
+- [examples/README.md](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/examples/README.md): the structure of the PLECS models and their agreement with *motulator*
+- [motulator_export/simulink/README.md](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/motulator_export/simulink/README.md): the structure of the Simulink models and their agreement with *motulator*
+- [motulator_export/c/README.md](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/motulator_export/c/README.md): the C port of the control algorithms
+- [motulator_export/matlab/README.md](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/motulator_export/matlab/README.md): the MATLAB port
+
+## License
+
+[MIT](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/LICENSE)

motulator_export-0.7.0/README.md

@@ -0,0 +1,61 @@
+# motulator-export
+
+Export [*motulator*](https://github.com/Aalto-Electric-Drives/motulator) drive systems and grid converter systems to [PLECS](https://www.plexim.com/products/plecs) and [Simulink](https://www.mathworks.com/products/simulink.html), and simulate them natively in C.
+
+**Documentation:** https://aalto-electric-drives.github.io/motulator-export/
+
+Build the system in *motulator* as usual, then:
+
+```python
+from motulator_export import native, plecs, simulink
+
+plecs.write_model("drive.plecs", mdl, ctrl, t_stop=1.2)  # PLECS model
+simulink.write_model("drive.slx", mdl, ctrl, t_stop=1.2)  # Simulink model
+res = native.Simulation(mdl, ctrl).simulate(t_stop=1.2)  # Native simulation
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Aalto-Electric-Drives/motulator-export/main/docs/source/images/plecs_drive_black.png">
+  <img alt="PLECS model of a 2.2-kW IPMSM drive" src="https://raw.githubusercontent.com/Aalto-Electric-Drives/motulator-export/main/docs/source/images/plecs_drive.png">
+</picture>
+
+*PLECS model of a 2.2-kW IPMSM drive with sensorless flux-vector control, written by [examples/ipmsm_2kw_fvc.py](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/examples/ipmsm_2kw_fvc.py).*
+
+- **One control code everywhere.** The control algorithms of *motulator* are ported to C. The same code runs in PLECS, in Simulink, and in the native simulation.
+- **The structure of *motulator*.** Each class of the control system is a masked block with the arguments of its class, nested as in *motulator*. The parameters are set as in a *motulator* script, and they can be changed without Python.
+- **Verified.** The PLECS and Simulink models agree with *motulator* to about 1e-6 relative to the signal magnitudes, and the native simulation to the rounding errors.
+- **Fast.** The native simulation is 30 to 40 times faster than *motulator*, which is useful, e.g., for parameter sweeps.
+
+## Installation
+
+Python 3.12 or later. Install the package in a virtual environment, which also installs *motulator* 0.15.2 or a later 0.15 release:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+python -m pip install motulator-export
+```
+
+The examples are in the repository. To run them, clone the repository and install the package from it:
+
+```bash
+git clone https://github.com/Aalto-Electric-Drives/motulator-export
+cd motulator-export
+python -m pip install -e .
+python examples/ipmsm_2kw_fvc.py
+```
+
+Then open the model `examples/ipmsm_2kw_fvc.plecs` in PLECS. See the [documentation](https://aalto-electric-drives.github.io/motulator-export/guide/getting_started.html) for the requirements of PLECS, Simulink, and the native simulation.
+
+## Development
+
+Install the package with `pip install -e .[dev]` and run the tests with `pytest` (requires gcc). The implementation is described in the developer notes:
+
+- [examples/README.md](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/examples/README.md): the structure of the PLECS models and their agreement with *motulator*
+- [motulator_export/simulink/README.md](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/motulator_export/simulink/README.md): the structure of the Simulink models and their agreement with *motulator*
+- [motulator_export/c/README.md](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/motulator_export/c/README.md): the C port of the control algorithms
+- [motulator_export/matlab/README.md](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/motulator_export/matlab/README.md): the MATLAB port
+
+## License
+
+[MIT](https://github.com/Aalto-Electric-Drives/motulator-export/blob/main/LICENSE)

motulator_export-0.7.0/motulator_export/__init__.py

@@ -0,0 +1,13 @@
+"""
+Export motulator systems to PLECS and Simulink, and simulate them natively.
+
+The subpackages `plecs` and `simulink` write the models of a system built in
+motulator, and `native` simulates the system in C. All of them run the same C port of
+the control algorithms of motulator.
+
+"""
+
+from motulator_export import native, plecs, simulink
+from motulator_export.plecs._common import StepSignal
+
+__all__ = ["StepSignal", "native", "plecs", "simulink"]

motulator_export-0.7.0/motulator_export/c/README.md

@@ -0,0 +1,60 @@
+# C port
+
+C port of the *motulator* control algorithms and models, run in the C-Script blocks of the PLECS models, in the S-functions of the Simulink models, and in the libraries of the native simulation (`motulator_export.native`).
+The code follows the Python code of *motulator* closely, including the order of the state updates, and each header lists its Python counterparts.
+Optional parameters (`None` in *motulator*) are represented by `NAN`, and their defaults are resolved in the C code, as in *motulator*.
+
+Each class is a type with its functions (e.g., `FluxObserver` with `flux_observer_init`, `flux_observer_compute_output`, and `flux_observer_update`), which the blocks of the classes of the control systems run.
+The measurements, the feedback signals, and the references between the blocks are signal vectors (meas, fbk, and ref), whose layouts are defined in the headers of the control methods (e.g., `MEAS_WIDTH` and `FBK_w_M` in `sm_flux_vector.h`) with their pack and unpack functions.
+The whole-system functions (e.g., `vector_control_system_compute_output`) run the control system in one block; they are used by the reference control systems of the tests.
+Their gate enable (`ControlSystem.set_enable` of *motulator*) selects the standby output of the controllers (e.g., `flux_vector_ctrl_compute_standby_output`) with the measured converter voltage, as in *motulator*; in the blocks of the classes, the block `compute_standby_output` of each controller selects the references.
+
+| File                   | Contents                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `common.c`             | `PIController`, `ComplexPIController`, `SpeedController`, `SpeedObserver`, `CurrentLimiter`, `PowerReferenceLimiter`, `RateLimiter`, `PWM` (MPE or MME overmodulation, double or single update) (with the duty-ratio error model `InverterNonlinearity` of the dead time and the threshold voltage, the current direction given by `np.sign` or `tanh(i/i_0)`), the discretization of the observers (`hold_equivalent` and `matched_pole`), root finding (`brentq`), and utility functions |
+| `gradnet.c`            | GradNet inference (`FluxMap`, `CurrentMap`, and `CurrentMapWithHarmonics`)                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `sm_parameters.c`      | `SynchronousMachinePars` and `SaturatedSynchronousMachinePars` (flux linkage, incremental inductances, and current iteration)                                                                                                                                                                                                                                                                                                                                                              |
+| `sm_control_loci.c`    | `ControlLoci` (MTPA, MTPV, and current-limit loci)                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `sm_flux_vector.c`     | `FluxObserver`, `SpeedFluxObserver`, `ReferenceGenerator`, `FluxTorqueController`, `FluxVectorController`, and `VectorControlSystem` for synchronous machines                                                                                                                                                                                                                                                                                                                              |
+| `sm_machine.c`         | `SynchronousMachine` with `SpatialSaturatedSynchronousMachinePars` and `MechanicalSystem`                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `im_current_vector.c`  | `FluxObserver`, `SpeedFluxObserver`, `CurrentReferenceGenerator`, `CurrentController`, `CurrentVectorController`, and `VectorControlSystem` for induction machines                                                                                                                                                                                                                                                                                                                         |
+| `im_flux_vector.c`     | `FluxTorqueController`, `ReferenceGenerator`, `ObserverBasedVHzController` (including open-loop V/Hz control with `L_M = inf`), and `VHzControlSystem` with the `RateLimiter` of the speed reference for induction machines                                                                                                                                                                                                                                                                |
+| `gfl_current_vector.c` | Grid-following `CurrentVectorController` (`PLL`, `CurrentController`, and the current and power references) and `GridConverterControlSystem`                                                                                                                                                                                                                                                                                                                                               |
+| `gfm_observer.c`       | Disturbance-observer-based grid-forming control (the discrete-time `Observer` and `ObserverBasedGridFormingController`) and `GridConverterControlSystem`                                                                                                                                                                                                                                                                                                                                   |
+| `sim.c`                | Native simulation: `Simulation` (the simulation loop, a single model and control system, the gates enabled) with the RK45 solver of scipy, the computational delay (`Delay`), the PWM models `ZOH` and `CarrierComparison`, `VoltageSourceConverter` with a constant DC-bus voltage or a DC-bus model (`DCBus` or `DiodeBridgeDCBus`), `StepSignal`, and the logs of the results                                                                                                           |
+| `drive.c`              | Native simulation: `Drive` with `SynchronousMachine` (`SynchronousMachinePars` or `SpatialSaturatedSynchronousMachinePars` with a GradNet current map with spatial harmonics) or `InductionMachine` (constant parameters), and `MechanicalSystem`                                                                                                                                                                                                                                          |
+| `grid.c`               | Native simulation: `GridConverterSystem` with `LFilter` or `LCLFilter` and `ThreePhaseSource`                                                                                                                                                                                                                                                                                                                                                                                              |
+| `native_sm.c`          | Native simulation: the library of synchronous machine drives with flux-vector control (`sm_flux_vector.c` and `drive.c`), with its API for Python                                                                                                                                                                                                                                                                                                                                          |
+| `native_im.c`          | Native simulation: the library of induction machine drives with current-vector control or observer-based V/Hz control (`im_current_vector.c`, `im_flux_vector.c`, and `drive.c`)                                                                                                                                                                                                                                                                                                           |
+| `native_gfl.c`         | Native simulation: the library of grid converter systems with grid-following control (`gfl_current_vector.c` and `grid.c`)                                                                                                                                                                                                                                                                                                                                                                 |
+| `native_gfm.c`         | Native simulation: the library of grid converter systems with grid-forming control (`gfm_observer.c` and `grid.c`)                                                                                                                                                                                                                                                                                                                                                                         |
+| `native.c`             | Native simulation: the helpers of the libraries (the limited voltage reference and the settings of the PWM)                                                                                                                                                                                                                                                                                                                                                                                |
+
+## Native simulation
+
+The libraries of the native simulation (`native_<name>.c`) combine the C port of a control system with C models of the system, which `sim.c` simulates as the simulation of *motulator* (`Simulation.simulate`): the control system is run at its sampling instants, the duty ratios pass through the computational delay and the PWM model, and the states are integrated between the sampling and switching instants by a port of the RK45 solver of scipy, taking the same steps.
+A model (`Model` in `sim.h`) and a control system (`ControlSystem`) are interfaces of function pointers, embedded as the first members of the concrete types (e.g., `Drive` in `drive.h`).
+The API functions setting the converter, its DC bus, and its modulator are in `sim.c`, those of the models in `drive.c` and `grid.c`, and those of the control systems in the libraries.
+The states are complex and in the order of *motulator*, and the control system logs the signal groups of *motulator* (`ref` and `fbk`), described by a string of their fields (e.g., `FVC_FIELDS` in `native_sm.c`), so that the Python module fills the time series of the *motulator* objects and post-processes them as *motulator* does.
+A new type of system needs its C model (e.g., a machine in `drive.c`), a library combining the model with the C port of its control system, and a Python module setting the parameters (e.g., `motulator_export/native/_im.py`).
+
+The native simulation takes the same solver steps as *motulator*, so the results agree to the rounding errors: about 1e-12 relative to the signal magnitudes, also with the GradNet models, see `tests/test_native.py`.
+With the carrier comparison (`pwm=True`), a rounding error can change a quantized duty ratio and thereby a switching instant, after which the solutions differ more; with a fine quantization (`CarrierComparison(N=2**24)`), they agree to about 1e-7.
+Similarly, the diode bridge (`DiodeBridgeDCBus`) clamps its inductor current at zero, which makes the step sizes sensitive to the rounding errors (differences of about 1e-7 to 1e-5, depending on the system and the simulated time).
+The closed-loop simulations of *motulator* itself are equally sensitive to the rounding errors.
+
+## Tests
+
+The tests in `tests/` compile the C sources with gcc and compare the results with *motulator* step by step, without PLECS.
+They run in GitHub Actions on every push and weekly against the main branch of *motulator*, to detect changes in *motulator* that must be mirrored here.
+
+## GradNets
+
+Both *motulator* and the C port evaluate the GradNets in double precision, and the incremental inductances are computed from the analytic Jacobian of the flux map in both, so the tests compare the C port with *motulator* using the relative tolerance of 1e-9.
+The sizes of the networks are limited by `GRADNET_MAX_IN_DIM` and `GRADNET_MAX_EMBED_DIM` in `gradnet.h`, which are checked both when a model is written and at the start of the simulation.
+
+## Portability
+
+The C port uses the C99 complex type (`complex.h`) in double precision, mirroring the complex space vectors of *motulator*.
+It compiles with gcc, clang, MinGW-w64 (e.g., for `mex` in MATLAB), and the compiler bundled with PLECS, but not with MSVC, and embedded compilers may lack `complex.h`.
+A conversion to a custom complex type or to single precision is straightforward with the C-port tests, but it is left until a concrete embedded target exists.