Simulink Python binding generator.
Project description
SlxPy
Toolchain for seamlessly generating efficient Simulink-to-Python binding and gymnasium-like environment wrapper.
Forked from slxpy
, the Simulink-to-Python C++ bindings generator as Python package and MATLAB toolbox:
Table of Contents
- SlxPy
Flowchart
The flowchart briefly describes common workflow for your smoother integration.
graph TD;
Learn[Learn fundamentals];
Prerequisities[Prerequisities];
Installation[Installation];
Model[Prepare model];
Create[Create project];
Setup["(MATLAB) slxpy.setup_config(project_path)"];
Codegen["(MATLAB) slxpy.codegen(project_path)"];
Generate["(CLI) slxpy generate"];
Build["(CLI) python setup.py build"];
Test["Test & Done"];
MTC(["On model.toml change"]);
MC(["On model change"]);
ETC(["On env.toml change"]);
subgraph Preparation
Prerequisities --> Installation;
end
Installation --> Create;
subgraph Main workflow
Create --> Setup --> Codegen --> Generate --> Build --> Test;
Model --> Setup;
MTC --Rerun--> Setup;
MC --Rerun--> Codegen;
ETC --Rerun--> Generate;
end
Features
- Almost complete Simulink and Embedded Coder features support
- Compatible with a wide range of MATLAB versions
- Help tuning Simulink code generation config
- Mininal dependencies and cross-platform, not depending on MATLAB after Simulink code generation step
- Exchange array data with numpy for efficiency
- Raw and gymnasium (formerly gym) environment wrapper, with seeding and parameter randomization support
- Automatic single-node parallelization with vector environment
- Generate human-readable object
__repr__
for ease of use - Automatically generate stub file to assist development (with pybind11-stubgen)
- Compile with all modern C++ compilers
Prerequisities & Installation & Quick start
You need to prepare Python, optionally MATLAB and a C++ compiler to begin with slxpy.
MATLAB
-
Only needed for
Step 2
(Simulink to C++) -
Version: >= R2018a ( >= R2021a recommended )
-
R2021a may be the first version actually suitable for RL environment as it allows
instance parameters
. Previous versions of Embedded Coder will generates static parameters which might be difficult to use in a program (shared by all instances). -
For version >= R2018a, limited support is added.
MATLAB prior to R2021a will inline parameters defined in model workspace when C++ interface is chosen. The script has some logic to allow you to code as R2021 workflow, and maintain tunability on prior to R2021a releases, but the script may fail on the first run and work for following runs due to unknown reasons. (In R2021a it's far easier)
-
For version <= R2017b, some Simulink internal error prohibits proper code generation, thus unsupported.
-
MATLAB since R2022a supports reusable Simscape model, and slxpy provides corresponding support. Simscape enables powerful non-causal system modeling, which may be very useful for environment design.
After Mathworks ticket 05353942 & 05373346, reusable C++ class in this release is an unintended bug, and only reusable C interface is officially supported. So, it may not yet work as expected. (Bug/Enhancement Submitted)
-
-
Toolbox: Simulink, Embedded Coder, MATLAB Coder, Simulink Coder
Python
-
Almost always needed, except for
Step 2
-
Version: >= 3.8 (but generated binding can target Python 3.7)
Slxpy uses a bunch of features added in Python 3.8
C++ toolchain
-
Needed for
Step 4
(Building C++)For
Step 2
, Embedded Coder does not depend on a C++ toolchain to generate code, but may display a warning for failing to generate build files, which is OK.For some MATLAB versions, however, if you are facing error like this:
The model is configured for C++ code generation, but the C-only compiler, LCC, is the default compiler. To allow code generation, on the Code Generation pane:
- Select the 'Generate code only' check box.
- In the Toolchain field, select a toolchain from the drop-down list.
it may be a logic error in Embedded Coder. Just select an alternative C++ toolchain other than LCC, even if it does not exist in your system.
-
C++ 17 compatible compiler (one of)
- for Windows, Visual Studio 2019 or newer
- Clang 5 or newer
- GCC 7 or newer
Installation
You need to install two packages, one Python package for Python main logic, one MATLAB toolbox for MATLAB interop.
-
Install Python package with
pip install slxpy
It is recommanded to use slxpy with conda (to enable multi-target build) and install slxpy in an dedicated conda environment, i.e.
conda create -n slxpy python=3.9 conda activate slxpy pip install slxpy
-
Install MATLAB toolbox
Downloading toolbox from File Exchange link and double-click it in MATLAB to install.
Quick start
-
Prepare a Simulink model
foo.slx
suitable for code generation (See docs/modeling.md) -
Project creation
mkdir bar # Create slxpy project folder, choose any name you like cd bar slxpy init # Interactively fill up basic information
Then adjust
model.toml
andenv.toml
as needed (See comments in file, and also docs/env.md). -
Simulink code generation
workdir = 'bar'; % Path to slxpy project folder slxpy.setup_config(workdir) % Only need to be run for the first time slxpy.codegen(workdir) % Code generation
-
Slxpy asset generation
# Assuming still in bar folder slxpy generate
-
Build extension
# Assuming still in bar folder python setup.py build
-
Test extension
# Assuming still in bar folder cd build/lib<platform-suffix> python
In Python REPL, run
# Substitute foo & bar to your corresponding model & project name import bar a = bar.fooModelClass() b = bar.RawEnv() c = bar.RawEnvVec() d = bar.GymEnv() e = bar.GymEnvVec() # Could also provide an EnvSpec similar to Gym's EnvSpec # Check stub or call help(bar._env.EnvSpec) for more options. spec = bar._env.EnvSpec( id='bar-v0', max_episode_steps=100, strict_reset=True, ) env = bar.GymEnv(spec)
Modeling guide
Slxpy follows standard simulink code generation process. So, if your model follows standard, minimal adjustments are required for proper code generation. So, detailed discussion about Simulink modeling is out of scope for this README, you shall refer to Simulink documentation for instructions.
To support gym environment generation, see Gym Support section.
Tunable parameter
To make environment tunable, thus could have randomness, physical parameters, random seed, initial state of intergrator, etc shall be created with following two steps.
- Set them in
Model workspace
asSimulink Parameter
. If it's aMATLAB variable
rather than aSimulink Parameter
, right-click entries, selectConvert to parameter object
to convert. - Tick the
Argument
checkbox.
Limitations by Embedded Coder
- S Function: You have to provide a
.tlc
file for S Function code generation, but.tlc
is a difficult topic. So, I recommend usingMATLAB Function
block when possible. - Fixed-step Solver: Variable-step solver do not support code generation in Embedded Coder. (Some models may get wrong simulation result in Fixed-step Solver if numeric condition is bad. Make sure to validate before code generation for proper results.)
- Algebraic Loop: Simulink could partially handle algebraic loop, but code generation does not. Try avoiding it using a
Unit Delay
orMemory
block, or solve it iteratively in aMATLAB Function
block. - Variable-sized input: Embedded Coder C++ interface do not support it.
- Other blocks not supported by code generation, refer to Simulink documentation
Limitations by Slxpy
-
Variable-sized output: difficult to handle properly, currently not considered
-
Fixed-point data: difficult to handle properly, currently not considered
-
Bitfield: difficult to handle properly, currently not considered
-
Event/function-call based system: difficult to handle properly, currently not considered
-
String: string-related blocks are not supported. String
std::string
lead to non-POD struct in C++, breaking a fundemental assumption for Slxpy
Luckily, entries mentioned above might rarely be used in modeling.
Gym Support
If modeling properly, Slxpy could generate gym environment with minimal configuration.
Model requirement
- One inport of data type
double
(default) as action. Recommend to have exactly one inport, as additional inports will get zero input (meaningless). - One output of data type
double
(default) as observation. Recommend to be the first outport. - One scalar output of data type
double
(default) as reward. Recommend to be the second outport. - One scalar output of data type
logical
as done. Recommend to be the third outport. - Any additional outports of data type
double
(default) to be included in info dict.
env.toml
Configuration file env.toml
can be used to control various aspects of environment wrapping, including action_space, observation_space, initial observation and parameter initialization.
Basic setting
## Config version. DO NOT CHANGE.
__version__ = "1.0.0"
## Generate raw environment wrapper.
use_raw = true
## Generate gym-flavor environment wrapper (tensor action, tensor observation).
## NOTE: gym-flavor environment has to meet certain criteria. See "gym" section below.
use_gym = true
## Environment initialization needs randomness (generally true).
use_rng = true
## Generate vectorized wrapper over raw/gym environment.
use_vec = true
Configure gym-simulink mapping and gym space
## Configure gym-simulink mapping.
[gym]
## Action key in model inport(s).
## Data MUST be a double scalar or array.
## By default, the 1st inport is taken (Generally only one inport is sensible).
## Uncomment the line below to provide an alternative key.
# action_key = "act"
## Observation key in model outports.
## Data MUST be a double scalar or array.
## By default, the 1st outport is taken.
## Uncomment the line below to provide an alternative key.
# observation_key = "obs"
## Reward key in model outports.
## Data MUST be a double scalar.
## By default, the 2nd outport is taken.
## Uncomment the line below to provide an alternative key.
# reward_key = "rew"
## Done key in model outports.
## Data MUST be a boolean (or logical in MATLAB) scalar.
## By default, the 3rd outport is taken.
## Uncomment the line below to provide an alternative key.
# done_key = "done"
## Put additional outports to info dict.
## Option: true -> all additional outports are included
## false -> empty info dict
## list of keys -> selected outports are included, e.g. ["foo", "bar"]
info = true
## Reward range, e.g. ["-inf", "inf"] | ["-inf", 0] | [-10, 10]
reward_range = ["-inf", "inf"]
## Action space, similar to gym.space
## "type" includes: Box, Discrete, MultiDiscrete, MultiBinary
[gym.action_space]
type = "Discrete"
n = 2
## Observation space, see action_space above
[gym.observation_space]
type = "Box"
low = 0.0
high = 1.0
shape = [2, 2]
dtype = "float64"
Control reset behavior to get initial observation
# Options controlling reset behavior
[reset]
## Take one step after environment initialization to get initial observation.
## If set to true/false, optionally provide a initializer for initial action/observation.
first_step = true
## Only valid when "first_step = true".
## By default, initial action is initialized with "default initialization".
## Uncomment the line below to provide an "aggregate initialization" list.
action = "{ 1.0 }"
## Only valid when "first_step = false".
## By default, initial observation is initialized with "default initialization"
## and might be affected by const block output optimization.
## Uncomment the line below to provide an "aggregate initialization" list.
# observation = "{ 1.0 }"
Define how parameters are initialized on each reset
## A table to define individual parameter initialization policy
[parameter]
[parameter.seed_1]
type = "seed"
[parameter.seed_2]
type = "seed"
[parameter.constant_1]
type = "constant"
value = 1.0
[parameter.constant_2]
type = "constant"
value = "{ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 }"
[parameter.uniform_1]
type = "uniform"
low = 0.0
high = 1.0
[parameter.uniform_2]
type = "uniform"
low = 0.0
high = 1.0
[parameter.uniform_3]
type = "uniform"
low = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]
high = 1.0
[parameter.uniform_4]
type = "uniform"
low = 0.0
high = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]
[parameter.uniform_5]
type = "uniform"
low = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]
high = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]
[parameter.custom]
type = "custom"
code = "std::fill_n(params.custom, 6, -1);"
Architecture
- Frontend: Convert source to IR
- Backend: Generate Pybind11 binding with IR and modern C++ features, using Jinja2 for template generation
FAQ
Numerous compiler errors about undefined identifier 'creal_T' with Simscape
Try to set simulink feature complex
to true
in model.toml
.
Though Embedded Coder did not complain, some Simscape (multibody) functions may implicitly depend on complex structs c*_T
.
This may be a flaw of Mathworks product design.
Implementation note
About stack allocation
Simulink structs could have arbitrary size, ranging from only one scalar field to a large array storing an image, previous implementation (88b504f and previous) has unintended stack allocations, which causes stack overflow and immediate abort for large structs.
After identifying the problem, stack allocations are changed to heap allocation and placement new.
About model class Copy/Move Constructible/Assignable
Simulink generated C++ class do not forbid these four default constructors, but pointers in RTModel may point to
invalid locations if initialize
is not called again.
So, avoid calling these four default constructors explicitly or implicitly.
Changelog
-
v1.6.0.post1
- New versioning scheme, forks from slxpy are now labeled as same version with a
.postN
suffix. - Baseline for fork. (No change from original Python implementation slxpy==v1.6.0)
- New versioning scheme, forks from slxpy are now labeled as same version with a
-
v1.6.1.post1
- Updated fork to slxpy==v1.6.1
-
v1.6.1.post2
- Based on v1.6.1.post1 with some improvements (the old fork version labeled slxpy==v1.6.2 is similar to slxpy-fork==v1.6.0.post1).
- Added model name and version via Jinja2 template of
setup.py
for better package management of compiled models. - Multi-line
json
files with indentations of four whitespaces for proper support of git tracking generated models.
-
v1.6.1.post3
- Minor changes to package information
-
v1.6.1.post4
- Use version strings instead of numbers that otherwise would be truncated with trailing zeros or result in parsing error.
-
v1.6.1.post5
- Improve test extension scripts to also work with pytest
- Structs are now read/write properties after pybind11 build if they are writable in the C++ code
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for slxpy_fork-1.6.1.post5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8c20fb42178b508939c8671b53172ba73c970d370e062fd187c625a3e2ace3a4 |
|
MD5 | 7d7e917f4dfbee0698b45c5f44349f63 |
|
BLAKE2b-256 | ad58e1451e006cb0fda784de476898e823d880cdf51d5b73f18539af8bbe43fe |