Skip to content

Commit 36e8a74

Browse files
alphavillealphaville
committed
[ci skip] some more cleanup
1 parent 34e075d commit 36e8a74

File tree

10 files changed

+282
-1240
lines changed

10 files changed

+282
-1240
lines changed

‎docs/content/matlab-api.mdx‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
---
2+
id: matlab-api
3+
title: MATLAB API
4+
description: TCP-based MATLAB API for parametric and OCP-generated OpEn optimizers
5+
---
6+
7+
# MATLAB API
8+
9+
This page documents the current MATLAB API of OpEn.
10+
11+
The current MATLAB interface lives in `matlab/api` and communicates with
12+
optimizers that were generated in Python and expose a TCP server.
13+
14+
If you are looking for the older MATLAB code-generation workflow, see the
15+
[legacy MATLAB interface](./matlab-interface) and the
16+
[MATLAB examples](./matlab-examples).
17+
18+
## Overview
19+
20+
The current MATLAB API supports:
21+
22+
- TCP-based calls to standard parametric optimizers
23+
- TCP-based calls to OCP-generated optimizers created with `opengen.ocp`
24+
- Loading `optimizer_manifest.json` for OCP optimizers
25+
- Automatic endpoint discovery from the sibling `optimizer.yml`
26+
- Warm-start inputs:
27+
- `InitialGuess`
28+
- `InitialLagrangeMultipliers`
29+
- `InitialPenalty`
30+
- Health-check and shutdown operations through `ping()` and `kill()`
31+
32+
The main MATLAB entry points are:
33+
34+
- `OpEnTcpOptimizer`
35+
- `createOpEnTcpOptimizer`
36+
37+
:::important
38+
The MATLAB API is a TCP client only. It does **not** start the optimizer
39+
server; the generated optimizer must already be running.
40+
:::
41+
42+
## Getting Started
43+
44+
Add the MATLAB API directory to your path:
45+
46+
```matlab
47+
addpath(fullfile(pwd, 'matlab', 'api'));
48+
```
49+
50+
Create a client using either:
51+
52+
- `OpEnTcpOptimizer(port)`
53+
- `OpEnTcpOptimizer(port, ip)`
54+
- `OpEnTcpOptimizer(ip, port)`
55+
56+
For example:
57+
58+
```matlab
59+
client = OpEnTcpOptimizer(3301);
60+
pong = client.ping();
61+
disp(pong.Pong);
62+
```
63+
64+
## Parametric Optimizers
65+
66+
For a standard parametric optimizer, call `solve` with the flat parameter
67+
vector:
68+
69+
```matlab
70+
client = OpEnTcpOptimizer(3301);
71+
72+
response = client.solve([2.0, 10.0]);
73+
74+
if response.ok
75+
disp(response.solution);
76+
disp(response.cost);
77+
disp(response.exit_status);
78+
else
79+
error('OpEn:SolverError', '%s', response.message);
80+
end
81+
```
82+
83+
You can also provide warm-start data:
84+
85+
```matlab
86+
response1 = client.solve([2.0, 10.0]);
87+
88+
response2 = client.solve( ...
89+
[2.0, 10.0], ...
90+
'InitialGuess', response1.solution, ...
91+
'InitialLagrangeMultipliers', response1.lagrange_multipliers, ...
92+
'InitialPenalty', response1.penalty);
93+
```
94+
95+
To stop the server gracefully:
96+
97+
```matlab
98+
client.kill();
99+
```
100+
101+
## OCP Optimizers
102+
103+
For OCP-generated optimizers, the MATLAB API uses the optimizer manifest to
104+
pack named parameter blocks into the flat parameter vector expected by the
105+
underlying TCP solver.
106+
107+
This matches the Python `GeneratedOptimizer.solve(...)` workflow conceptually,
108+
but in MATLAB you pass the values as **name-value pairs**.
109+
110+
### Loading an OCP Manifest
111+
112+
If `optimizer_manifest.json` and `optimizer.yml` are in the same generated
113+
optimizer directory, MATLAB can read the TCP endpoint automatically:
114+
115+
```matlab
116+
manifestPath = fullfile( ...
117+
pwd, ...
118+
'open-codegen', ...
119+
'.python_test_build_ocp', ...
120+
'ocp_single_tcp', ...
121+
'optimizer_manifest.json');
122+
123+
client = OpEnTcpOptimizer('ManifestPath', manifestPath);
124+
disp(client.parameterNames());
125+
```
126+
127+
You can also override the TCP endpoint explicitly:
128+
129+
```matlab
130+
client = OpEnTcpOptimizer(3391, 'ManifestPath', manifestPath);
131+
```
132+
133+
### Single-Shooting OCP Example
134+
135+
The following example uses a generated OCP optimizer whose manifest defines
136+
the parameter blocks `x0` and `xref`:
137+
138+
```matlab
139+
response = client.solve( ...
140+
'x0', [1.0, -1.0], ...
141+
'xref', [0.0, 0.0]);
142+
143+
if response.ok
144+
disp(response.solution);
145+
disp(response.inputs);
146+
disp(response.exit_status);
147+
else
148+
error('OpEn:SolverError', '%s', response.message);
149+
end
150+
```
151+
152+
If some manifest parameters have defaults, only the required ones need to be
153+
provided:
154+
155+
```matlab
156+
manifestPath = fullfile( ...
157+
pwd, ...
158+
'open-codegen', ...
159+
'.python_test_build_ocp', ...
160+
'ocp_manifest_bindings', ...
161+
'optimizer_manifest.json');
162+
163+
client = OpEnTcpOptimizer('ManifestPath', manifestPath);
164+
response = client.solve('x0', [1.0, 0.0]);
165+
```
166+
167+
### Multiple-Shooting OCP Example
168+
169+
For multiple-shooting OCPs, the MATLAB response also contains the reconstructed
170+
state trajectory:
171+
172+
```matlab
173+
manifestPath = fullfile( ...
174+
pwd, ...
175+
'open-codegen', ...
176+
'.python_test_build_ocp', ...
177+
'ocp_multiple_tcp', ...
178+
'optimizer_manifest.json');
179+
180+
client = OpEnTcpOptimizer('ManifestPath', manifestPath);
181+
182+
response = client.solve( ...
183+
'x0', [1.0, -1.0], ...
184+
'xref', [0.0, 0.0]);
185+
186+
disp(response.inputs);
187+
disp(response.states);
188+
```
189+
190+
### OCP Warm-Start Example
191+
192+
Warm-start options can be combined with the named OCP parameters:
193+
194+
```matlab
195+
response1 = client.solve( ...
196+
'x0', [1.0, -1.0], ...
197+
'xref', [0.0, 0.0]);
198+
199+
response2 = client.solve( ...
200+
'x0', [1.0, -1.0], ...
201+
'xref', [0.0, 0.0], ...
202+
'InitialGuess', response1.solution, ...
203+
'InitialLagrangeMultipliers', response1.lagrange_multipliers, ...
204+
'InitialPenalty', response1.penalty);
205+
```
206+
207+
## Response Format
208+
209+
All successful solver calls return the low-level solver fields produced by the
210+
TCP server, together with a MATLAB-friendly `ok` flag.
211+
212+
Typical fields include:
213+
214+
- `ok`
215+
- `solution`
216+
- `cost`
217+
- `exit_status`
218+
- `solve_time_ms`
219+
- `penalty`
220+
- `num_outer_iterations`
221+
- `num_inner_iterations`
222+
- `last_problem_norm_fpr`
223+
- `f1_infeasibility`
224+
- `f2_norm`
225+
- `lagrange_multipliers`
226+
227+
For OCP optimizers, the response also includes:
228+
229+
- `packed_parameter`
230+
- `inputs`
231+
- `states` for multiple-shooting formulations
232+
233+
## Related Pages
234+
235+
- [Python TCP/IP interface](./python-tcp-ip)
236+
- [Python OCP guide](./python-ocp-1)
237+
- [Legacy MATLAB interface](./matlab-interface)
238+
- [MATLAB examples](./matlab-examples)

‎docs/content/openrust-arithmetic.mdx‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,7 @@ precision arithmetic.
3131

3232
<Tabs>
3333

34-
35-
<TabItem value="using-f32" label="Single precision">
34+
<TabItem value="default-f32" label="Single precision" default>
3635

3736
```rust
3837
use optimization_engine::{constraints, panoc::PANOCCache, Problem, SolverError};
@@ -65,7 +64,7 @@ assert!(status.has_converged());
6564
```
6665
</TabItem>
6766

68-
<TabItem value="default-f64" label="Double precision" default>
67+
<TabItem value="f64" label="Double precision">
6968

7069
```rust
7170
use optimization_engine::{constraints, panoc::PANOCCache, Problem, SolverError};

‎docs/website/blog/2026-03-28-open-0-12-0.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Announcing OpEn 0.12.0 for Rust
3+
author: Pantelis Sopasakis
4+
authorURL: https://github.com/alphaville
5+
authorImageURL: https://avatars.githubusercontent.com/u/125415?v=4
6+
---
7+
8+
OpEn 0.12.0 brings important updates to the core Rust library.
9+
The key changes are:
10+
11+
- Support for both `f32` and `f64` ([docs](/optimization-engine/docs/openrust-arithmetic))
12+
- Better error handling and reporting
13+
- Using [web-time](https://crates.io/crates/web-time) which works in browsers
14+
15+
<!-- truncate -->
16+
17+
## Highlights
18+
19+
### Support for both `f32` and `f64`
20+
21+
The Rust solver now supports generic floating-point types, so you can work with either `f32` or `f64` depending on your target platform and performance needs.
22+
23+
This is particularly useful for embedded and resource-constrained systems, where `f32` can be a better fit, while `f64` remains available for applications that need higher precision.
24+
25+
### Replaced `instant` and wasm with `web-time`
26+
27+
The timing layer has been simplified by switching to `web-time`.
28+
29+
This replaces the previous `instant` setup and the extra wasm-specific feature wiring around it, making timing support cleaner and more portable across native and web-oriented targets.
30+
31+
### Better error handling
32+
33+
Error reporting in the Rust library has been significantly improved.
34+
35+
Projection failures, invalid numerical states, linear algebra failures, and other internal solver issues now surface as richer Rust-side errors with clearer, human-readable explanations. Constraint projections are also fallible now, which means these failures can propagate through FBS, PANOC, and ALM instead of being silently flattened into harder-to-debug behavior.
36+
37+
## See also
38+
39+
- [Rust documentation](/optimization-engine/docs/openrust-basic)
40+
- [Rust features](/optimization-engine/docs/openrust-features)
41+
- [Project repository](https://github.com/alphaville/optimization-engine)

‎docs/website/sidebars.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ module.exports = {
3232
{
3333
type: 'category',
3434
label: 'MATLAB',
35-
items: ['matlab-interface', 'matlab-examples'],
35+
items: ['matlab-api', 'matlab-interface', 'matlab-examples'],
3636
},
3737
{
3838
type: 'category',

0 commit comments

Comments
 (0)