# SlxPy
[](https://pypi.org/project/slxpy-fork)
[](https://github.com/Pythoniasm/slxpy-fork)
Toolchain for seamlessly generating efficient Simulink-to-Python binding and gymnasium-like environment wrapper.
Forked from [`slxpy`](https://pypi.org/project/slxpy), the Simulink-to-Python C++ bindings generator as Python package and MATLAB toolbox:
[](https://pypi.org/project/slxpy)
[](https://www.mathworks.com/matlabcentral/fileexchange/100416-slxpy)
## Table of Contents
- [SlxPy](#slxpy)
- [Table of Contents](#table-of-contents)
- [Flowchart](#flowchart)
- [Features](#features)
- [Prerequisities \& Installation \& Quick start](#prerequisities--installation--quick-start)
- [MATLAB](#matlab)
- [Python](#python)
- [C++ toolchain](#c-toolchain)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Modeling guide](#modeling-guide)
- [Tunable parameter](#tunable-parameter)
- [Limitations by Embedded Coder](#limitations-by-embedded-coder)
- [Limitations by Slxpy](#limitations-by-slxpy)
- [Gym Support](#gym-support)
- [Model requirement](#model-requirement)
- [env.toml](#envtoml)
- [Basic setting](#basic-setting)
- [Configure gym-simulink mapping and gym space](#configure-gym-simulink-mapping-and-gym-space)
- [Control reset behavior to get initial observation](#control-reset-behavior-to-get-initial-observation)
- [Define how parameters are initialized on each reset](#define-how-parameters-are-initialized-on-each-reset)
- [Architecture](#architecture)
- [FAQ](#faq)
- [Numerous compiler errors about undefined identifier 'creal\_T' with Simscape](#numerous-compiler-errors-about-undefined-identifier-creal_t-with-simscape)
- [Implementation note](#implementation-note)
- [About stack allocation](#about-stack-allocation)
- [About model class Copy/Move Constructible/Assignable](#about-model-class-copymove-constructibleassignable)
- [Changelog](#changelog)
## Flowchart
The flowchart briefly describes common workflow for your smoother integration.
```mermaid
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:
>
> 1. Select the 'Generate code only' check box.
> 2. 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.
1. 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
```
2. Install MATLAB toolbox
Downloading toolbox from [File Exchange link](https://www.mathworks.com/matlabcentral/fileexchange/100416-slxpy) and double-click it in MATLAB to install.
## Quick start
0. Prepare a Simulink model `foo.slx` suitable for code generation (See [docs/modeling.md](docs/modeling.md))
1. Project creation
```bash
mkdir bar # Create slxpy project folder, choose any name you like
cd bar
slxpy init # Interactively fill up basic information
```
Then adjust `model.toml` and `env.toml` as needed (See comments in file, and also [docs/env.md](docs/env.md)).
2. Simulink code generation
```matlab
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
```
3. Slxpy asset generation
```bash
# Assuming still in bar folder
slxpy generate
```
4. Build extension
```bash
# Assuming still in bar folder
python setup.py build
```
5. Test extension
```bash
# Assuming still in bar folder
cd build/lib<platform-suffix>
python
```
In Python REPL, run
```python
# 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` as `Simulink Parameter`. If it's a `MATLAB variable` rather than a `Simulink Parameter`, right-click entries, select `Convert 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 using `MATLAB 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` or `Memory` block, or solve it iteratively in a `MATLAB 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
```toml
## 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
```toml
## 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
```toml
# 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
```toml
## 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)
- 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
Raw data
{
"_id": null,
"home_page": "https://github.com/Pythoniasm/slxpy-fork",
"name": "slxpy-fork",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "simulink,c++,gym,gymnasium",
"author": "Jiang Yuxuan",
"author_email": "jyx21@mails.tsinghua.edu.cn",
"download_url": "https://files.pythonhosted.org/packages/72/1f/e184d40d98d0c35d09d5cbedc1ba8d9a2e62995f10dd10ca1d706eb161e6/slxpy-fork-1.6.1.post5.tar.gz",
"platform": null,
"description": "# SlxPy\r\n\r\n[](https://pypi.org/project/slxpy-fork)\r\n[](https://github.com/Pythoniasm/slxpy-fork)\r\n\r\nToolchain for seamlessly generating efficient Simulink-to-Python binding and gymnasium-like environment wrapper.\r\n\r\nForked from [`slxpy`](https://pypi.org/project/slxpy), the Simulink-to-Python C++ bindings generator as Python package and MATLAB toolbox:\r\n[](https://pypi.org/project/slxpy)\r\n[](https://www.mathworks.com/matlabcentral/fileexchange/100416-slxpy)\r\n\r\n## Table of Contents\r\n- [SlxPy](#slxpy)\r\n - [Table of Contents](#table-of-contents)\r\n - [Flowchart](#flowchart)\r\n - [Features](#features)\r\n - [Prerequisities \\& Installation \\& Quick start](#prerequisities--installation--quick-start)\r\n - [MATLAB](#matlab)\r\n - [Python](#python)\r\n - [C++ toolchain](#c-toolchain)\r\n - [Installation](#installation)\r\n - [Quick start](#quick-start)\r\n - [Modeling guide](#modeling-guide)\r\n - [Tunable parameter](#tunable-parameter)\r\n - [Limitations by Embedded Coder](#limitations-by-embedded-coder)\r\n - [Limitations by Slxpy](#limitations-by-slxpy)\r\n - [Gym Support](#gym-support)\r\n - [Model requirement](#model-requirement)\r\n - [env.toml](#envtoml)\r\n - [Basic setting](#basic-setting)\r\n - [Configure gym-simulink mapping and gym space](#configure-gym-simulink-mapping-and-gym-space)\r\n - [Control reset behavior to get initial observation](#control-reset-behavior-to-get-initial-observation)\r\n - [Define how parameters are initialized on each reset](#define-how-parameters-are-initialized-on-each-reset)\r\n - [Architecture](#architecture)\r\n - [FAQ](#faq)\r\n - [Numerous compiler errors about undefined identifier 'creal\\_T' with Simscape](#numerous-compiler-errors-about-undefined-identifier-creal_t-with-simscape)\r\n - [Implementation note](#implementation-note)\r\n - [About stack allocation](#about-stack-allocation)\r\n - [About model class Copy/Move Constructible/Assignable](#about-model-class-copymove-constructibleassignable)\r\n - [Changelog](#changelog)\r\n\r\n\r\n## Flowchart\r\nThe flowchart briefly describes common workflow for your smoother integration.\r\n\r\n```mermaid\r\ngraph TD;\r\n Learn[Learn fundamentals];\r\n Prerequisities[Prerequisities];\r\n Installation[Installation];\r\n Model[Prepare model];\r\n Create[Create project];\r\n Setup[\"(MATLAB) slxpy.setup_config(project_path)\"];\r\n Codegen[\"(MATLAB) slxpy.codegen(project_path)\"];\r\n Generate[\"(CLI) slxpy generate\"];\r\n Build[\"(CLI) python setup.py build\"];\r\n Test[\"Test & Done\"];\r\n\r\n MTC([\"On model.toml change\"]);\r\n MC([\"On model change\"]);\r\n ETC([\"On env.toml change\"]);\r\n\r\n subgraph Preparation\r\n Prerequisities --> Installation;\r\n end\r\n Installation --> Create;\r\n subgraph Main workflow\r\n Create --> Setup --> Codegen --> Generate --> Build --> Test;\r\n Model --> Setup;\r\n MTC --Rerun--> Setup;\r\n MC --Rerun--> Codegen;\r\n ETC --Rerun--> Generate;\r\n end\r\n```\r\n\r\n## Features\r\n\r\n- Almost complete Simulink and Embedded Coder features support\r\n- Compatible with a wide range of MATLAB versions\r\n- Help tuning Simulink code generation config\r\n- Mininal dependencies and cross-platform, not depending on MATLAB after Simulink code generation step\r\n- Exchange array data with numpy for efficiency\r\n- Raw and gymnasium (formerly gym) environment wrapper, with seeding and parameter randomization support\r\n- Automatic single-node parallelization with vector environment\r\n- Generate human-readable object `__repr__` for ease of use\r\n- Automatically generate stub file to assist development (with pybind11-stubgen)\r\n- Compile with all modern C++ compilers\r\n\r\n## Prerequisities & Installation & Quick start\r\n\r\nYou need to prepare Python, optionally MATLAB and a C++ compiler to begin with slxpy.\r\n\r\n### MATLAB\r\n\r\n- Only needed for `Step 2` (Simulink to C++)\r\n\r\n- **Version**: >= R2018a ( >= **R2021a** recommended )\r\n\r\n - **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).\r\n - For version >= R2018a, limited support is added.\r\n\r\n 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)\r\n\r\n - For version <= R2017b, some Simulink internal error prohibits proper code generation, thus unsupported.\r\n\r\n - 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.\r\n\r\n 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)\r\n\r\n- **Toolbox**: Simulink, Embedded Coder, MATLAB Coder, Simulink Coder\r\n\r\n### Python\r\n\r\n- Almost always needed, except for `Step 2`\r\n- **Version**: >= 3.8 (but generated binding can target Python 3.7)\r\n\r\n Slxpy uses a bunch of features added in Python 3.8\r\n\r\n### C++ toolchain\r\n\r\n- Needed for `Step 4` (Building C++)\r\n\r\n 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.\r\n\r\n For some MATLAB versions, however, if you are facing error like this:\r\n > 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:\r\n >\r\n > 1. Select the 'Generate code only' check box.\r\n > 2. In the Toolchain field, select a toolchain from the drop-down list.\r\n\r\n 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.\r\n\r\n- C++ 17 compatible compiler (one of)\r\n - for Windows, Visual Studio 2019 or newer\r\n - Clang 5 or newer\r\n - GCC 7 or newer\r\n\r\n## Installation\r\nYou need to install two packages, one Python package for Python main logic, one MATLAB toolbox for MATLAB interop.\r\n\r\n1. Install Python package with `pip install slxpy`\r\n\r\n It is recommanded to use slxpy with conda (to enable multi-target build) and install slxpy in an dedicated conda environment, i.e.\r\n ```\r\n conda create -n slxpy python=3.9\r\n conda activate slxpy\r\n pip install slxpy\r\n ```\r\n\r\n2. Install MATLAB toolbox\r\n\r\n\tDownloading toolbox from [File Exchange link](https://www.mathworks.com/matlabcentral/fileexchange/100416-slxpy) and double-click it in MATLAB to install.\r\n\r\n## Quick start\r\n\r\n0. Prepare a Simulink model `foo.slx` suitable for code generation (See [docs/modeling.md](docs/modeling.md))\r\n\r\n1. Project creation\r\n\r\n ```bash\r\n mkdir bar # Create slxpy project folder, choose any name you like\r\n cd bar\r\n slxpy init # Interactively fill up basic information\r\n ```\r\n\r\n Then adjust `model.toml` and `env.toml` as needed (See comments in file, and also [docs/env.md](docs/env.md)).\r\n\r\n2. Simulink code generation\r\n\r\n ```matlab\r\n workdir = 'bar'; % Path to slxpy project folder\r\n slxpy.setup_config(workdir) % Only need to be run for the first time\r\n slxpy.codegen(workdir) % Code generation\r\n ```\r\n\r\n3. Slxpy asset generation\r\n\r\n ```bash\r\n # Assuming still in bar folder\r\n slxpy generate\r\n ```\r\n\r\n4. Build extension\r\n\r\n ```bash\r\n # Assuming still in bar folder\r\n python setup.py build\r\n ```\r\n\r\n5. Test extension\r\n\r\n ```bash\r\n # Assuming still in bar folder\r\n cd build/lib<platform-suffix>\r\n python\r\n ```\r\n\r\n In Python REPL, run\r\n\r\n ```python\r\n # Substitute foo & bar to your corresponding model & project name\r\n import bar\r\n a = bar.fooModelClass()\r\n b = bar.RawEnv()\r\n c = bar.RawEnvVec()\r\n d = bar.GymEnv()\r\n e = bar.GymEnvVec()\r\n\r\n # Could also provide an EnvSpec similar to Gym's EnvSpec\r\n # Check stub or call help(bar._env.EnvSpec) for more options.\r\n spec = bar._env.EnvSpec(\r\n id='bar-v0',\r\n max_episode_steps=100,\r\n strict_reset=True,\r\n )\r\n env = bar.GymEnv(spec)\r\n ```\r\n\r\n\r\n## Modeling guide\r\n\r\nSlxpy 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.\r\n\r\nTo support gym environment generation, see Gym Support section.\r\n\r\n### Tunable parameter\r\n\r\nTo make environment tunable, thus could have randomness, physical parameters, random seed, initial state of intergrator, etc shall be created with following two steps.\r\n\r\n- Set them in `Model workspace` as `Simulink Parameter`. If it's a `MATLAB variable` rather than a `Simulink Parameter`, right-click entries, select `Convert to parameter object` to convert.\r\n- Tick the `Argument` checkbox.\r\n\r\n### Limitations by Embedded Coder\r\n\r\n- S Function: You have to provide a `.tlc` file for S Function code generation, but `.tlc` is a difficult topic. So, I recommend using `MATLAB Function` block when possible.\r\n- 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.)\r\n- Algebraic Loop: Simulink could partially handle algebraic loop, but code generation does not. Try avoiding it using a `Unit Delay` or `Memory` block, or solve it iteratively in a `MATLAB Function` block.\r\n- Variable-sized input: Embedded Coder C++ interface do not support it.\r\n- Other blocks not supported by code generation, refer to Simulink documentation\r\n\r\n### Limitations by Slxpy\r\n\r\n- Variable-sized output: difficult to handle properly, currently not considered\r\n- Fixed-point data: difficult to handle properly, currently not considered\r\n- Bitfield: difficult to handle properly, currently not considered\r\n- Event/function-call based system: difficult to handle properly, currently not considered\r\n\r\n- String: string-related blocks are not supported. String `std::string` lead to non-POD struct in C++, breaking a fundemental assumption for Slxpy\r\n\r\nLuckily, entries mentioned above might rarely be used in modeling.\r\n\r\n## Gym Support\r\n\r\nIf modeling properly, Slxpy could generate gym environment with minimal configuration.\r\n\r\n### Model requirement\r\n\r\n- One inport of data type `double` (default) as **action**. Recommend to have exactly one inport, as additional inports will get zero input (meaningless).\r\n- One output of data type `double` (default) as **observation**. Recommend to be the first outport.\r\n- One scalar output of data type `double` (default) as **reward**. Recommend to be the second outport.\r\n- One scalar output of data type `logical` as **done**. Recommend to be the third outport.\r\n- Any additional outports of data type `double` (default) to be included in **info** dict.\r\n\r\n### env.toml\r\n\r\nConfiguration file `env.toml` can be used to control various aspects of environment wrapping, including action_space, observation_space, initial observation and parameter initialization.\r\n\r\n#### Basic setting\r\n\r\n```toml\r\n## Config version. DO NOT CHANGE.\r\n__version__ = \"1.0.0\"\r\n\r\n## Generate raw environment wrapper.\r\nuse_raw = true\r\n\r\n## Generate gym-flavor environment wrapper (tensor action, tensor observation).\r\n## NOTE: gym-flavor environment has to meet certain criteria. See \"gym\" section below.\r\nuse_gym = true\r\n\r\n## Environment initialization needs randomness (generally true).\r\nuse_rng = true\r\n\r\n## Generate vectorized wrapper over raw/gym environment.\r\nuse_vec = true\r\n```\r\n\r\n#### Configure gym-simulink mapping and gym space\r\n\r\n```toml\r\n## Configure gym-simulink mapping.\r\n[gym]\r\n ## Action key in model inport(s).\r\n ## Data MUST be a double scalar or array.\r\n ## By default, the 1st inport is taken (Generally only one inport is sensible).\r\n ## Uncomment the line below to provide an alternative key.\r\n # action_key = \"act\"\r\n\r\n ## Observation key in model outports.\r\n ## Data MUST be a double scalar or array.\r\n ## By default, the 1st outport is taken.\r\n ## Uncomment the line below to provide an alternative key.\r\n # observation_key = \"obs\"\r\n\r\n ## Reward key in model outports.\r\n ## Data MUST be a double scalar.\r\n ## By default, the 2nd outport is taken.\r\n ## Uncomment the line below to provide an alternative key.\r\n # reward_key = \"rew\"\r\n\r\n ## Done key in model outports.\r\n ## Data MUST be a boolean (or logical in MATLAB) scalar.\r\n ## By default, the 3rd outport is taken.\r\n ## Uncomment the line below to provide an alternative key.\r\n # done_key = \"done\"\r\n\r\n ## Put additional outports to info dict.\r\n ## Option: true -> all additional outports are included\r\n ## false -> empty info dict\r\n ## list of keys -> selected outports are included, e.g. [\"foo\", \"bar\"]\r\n info = true\r\n\r\n ## Reward range, e.g. [\"-inf\", \"inf\"] | [\"-inf\", 0] | [-10, 10]\r\n reward_range = [\"-inf\", \"inf\"]\r\n\r\n ## Action space, similar to gym.space\r\n ## \"type\" includes: Box, Discrete, MultiDiscrete, MultiBinary\r\n [gym.action_space]\r\n type = \"Discrete\"\r\n n = 2\r\n\r\n ## Observation space, see action_space above\r\n [gym.observation_space]\r\n type = \"Box\"\r\n low = 0.0\r\n high = 1.0\r\n shape = [2, 2]\r\n dtype = \"float64\"\r\n```\r\n\r\n#### Control reset behavior to get initial observation\r\n\r\n```toml\r\n# Options controlling reset behavior\r\n[reset]\r\n ## Take one step after environment initialization to get initial observation.\r\n ## If set to true/false, optionally provide a initializer for initial action/observation.\r\n first_step = true\r\n\r\n ## Only valid when \"first_step = true\".\r\n ## By default, initial action is initialized with \"default initialization\".\r\n ## Uncomment the line below to provide an \"aggregate initialization\" list.\r\n action = \"{ 1.0 }\"\r\n\r\n ## Only valid when \"first_step = false\".\r\n ## By default, initial observation is initialized with \"default initialization\"\r\n ## and might be affected by const block output optimization.\r\n ## Uncomment the line below to provide an \"aggregate initialization\" list.\r\n # observation = \"{ 1.0 }\"\r\n```\r\n\r\n#### Define how parameters are initialized on each reset\r\n\r\n```toml\r\n## A table to define individual parameter initialization policy\r\n[parameter]\r\n[parameter.seed_1]\r\n type = \"seed\"\r\n\r\n[parameter.seed_2]\r\n type = \"seed\"\r\n\r\n[parameter.constant_1]\r\n type = \"constant\"\r\n value = 1.0\r\n\r\n[parameter.constant_2]\r\n type = \"constant\"\r\n value = \"{ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 }\"\r\n\r\n[parameter.uniform_1]\r\n type = \"uniform\"\r\n low = 0.0\r\n high = 1.0\r\n\r\n[parameter.uniform_2]\r\n type = \"uniform\"\r\n low = 0.0\r\n high = 1.0\r\n\r\n[parameter.uniform_3]\r\n type = \"uniform\"\r\n low = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]\r\n high = 1.0\r\n\r\n[parameter.uniform_4]\r\n type = \"uniform\"\r\n low = 0.0\r\n high = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]\r\n\r\n[parameter.uniform_5]\r\n type = \"uniform\"\r\n low = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]\r\n high = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]\r\n\r\n[parameter.custom]\r\n type = \"custom\"\r\n code = \"std::fill_n(params.custom, 6, -1);\"\r\n```\r\n\r\n## Architecture\r\n- Frontend: Convert source to IR\r\n- Backend: Generate Pybind11 binding with IR and modern C++ features, using Jinja2 for template generation\r\n\r\n## FAQ\r\n### Numerous compiler errors about undefined identifier 'creal_T' with Simscape\r\nTry to set simulink feature `complex` to `true` in `model.toml`.\r\nThough Embedded Coder did not complain, some Simscape (multibody) functions may implicitly depend on complex structs `c*_T`.\r\nThis may be a flaw of Mathworks product design.\r\n\r\n## Implementation note\r\n### About stack allocation\r\nSimulink structs could have arbitrary size, ranging from only one scalar field to a large array storing an image,\r\nprevious implementation (88b504f and previous) has unintended stack allocations,\r\nwhich causes stack overflow and immediate abort for large structs.\r\n\r\nAfter identifying the problem, stack allocations are changed to heap allocation and placement new.\r\n\r\n### About model class Copy/Move Constructible/Assignable\r\nSimulink generated C++ class do not forbid these four default constructors, but pointers in RTModel may point to\r\ninvalid locations if `initialize` is not called again.\r\nSo, avoid calling these four default constructors explicitly or implicitly.\r\n\r\n## Changelog\r\n\r\n- v1.6.0.post1\r\n - New versioning scheme, forks from slxpy are now labeled as same version with a `.postN` suffix.\r\n - Baseline for fork. (No change from original Python implementation slxpy==v1.6.0)\r\n\r\n- v1.6.1.post1\r\n - Updated fork to slxpy==v1.6.1\r\n\r\n- v1.6.1.post2\r\n - 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).\r\n - Added model name and version via Jinja2 template of `setup.py` for better package management of compiled models.\r\n - Multi-line `json` files with indentations of four whitespaces for proper support of git tracking generated models.\r\n\r\n- v1.6.1.post3\r\n - Minor changes to package information\r\n\r\n- v1.6.1.post4\r\n - Use version strings instead of numbers that otherwise would be truncated with trailing zeros or result in parsing error.\r\n\r\n- v1.6.1.post5\r\n - Improve test extension scripts to also work with pytest\r\n - Structs are now read/write properties after pybind11 build if they are writable in the C++ code\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simulink Python binding generator.",
"version": "1.6.1.post5",
"project_urls": {
"Homepage": "https://github.com/Pythoniasm/slxpy-fork"
},
"split_keywords": [
"simulink",
"c++",
"gym",
"gymnasium"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad58e1451e006cb0fda784de476898e823d880cdf51d5b73f18539af8bbe43fe",
"md5": "7d7e917f4dfbee0698b45c5f44349f63",
"sha256": "8c20fb42178b508939c8671b53172ba73c970d370e062fd187c625a3e2ace3a4"
},
"downloads": -1,
"filename": "slxpy_fork-1.6.1.post5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d7e917f4dfbee0698b45c5f44349f63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 372343,
"upload_time": "2024-02-27T20:40:39",
"upload_time_iso_8601": "2024-02-27T20:40:39.283539Z",
"url": "https://files.pythonhosted.org/packages/ad/58/e1451e006cb0fda784de476898e823d880cdf51d5b73f18539af8bbe43fe/slxpy_fork-1.6.1.post5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "721fe184d40d98d0c35d09d5cbedc1ba8d9a2e62995f10dd10ca1d706eb161e6",
"md5": "e60bfd62debbabb461dbed090aea4f63",
"sha256": "c3ae7a3292038721d8d1b02946b4fc62b019261fd07b670faa02e9d459824546"
},
"downloads": -1,
"filename": "slxpy-fork-1.6.1.post5.tar.gz",
"has_sig": false,
"md5_digest": "e60bfd62debbabb461dbed090aea4f63",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 331693,
"upload_time": "2024-02-27T20:40:43",
"upload_time_iso_8601": "2024-02-27T20:40:43.270458Z",
"url": "https://files.pythonhosted.org/packages/72/1f/e184d40d98d0c35d09d5cbedc1ba8d9a2e62995f10dd10ca1d706eb161e6/slxpy-fork-1.6.1.post5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-27 20:40:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Pythoniasm",
"github_project": "slxpy-fork",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "slxpy-fork"
}
JSON
