Skip to content

Commit b8fee87

Browse files
committed
docs: add multi-strategy routing documentation for route_to
Add section explaining how to route the same option to multiple strategies with different values using the syntax: route_to(strategy_id_1, val_1, strategy_id_2, val_2, ...)
1 parent 2ba73c6 commit b8fee87

1 file changed

Lines changed: 36 additions & 12 deletions

File tree

docs/src/manual-solve-advanced.md

Lines changed: 36 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -85,30 +85,54 @@ Use `route_to` to explicitly specify which **strategy** should receive the optio
8585
```julia
8686
# Explicitly route to the :exa strategy
8787
sol = solve(ocp, :exa, :madnlp;
88-
common_option_name=route_to(exa=12),
88+
common_option_name=route_to(:exa, 12),
8989
max_iter=500,
9090
print_level=MadNLP.ERROR
9191
)
9292
```
9393

9494
The `route_to` function accepts keyword arguments with **strategy names**:
9595

96-
- `route_to(collocation=value)` — route to the Collocation discretizer
97-
- `route_to(adnlp=value)` — route to the ADNLP modeler
98-
- `route_to(exa=value)` — route to the Exa modeler
99-
- `route_to(ipopt=value)` — route to the Ipopt solver
100-
- `route_to(madnlp=value)` — route to the MadNLP solver
101-
- `route_to(uno=value)` — route to the Uno solver
102-
- `route_to(madncl=value)` — route to the MadNCL solver
103-
- `route_to(knitro=value)` — route to the Knitro solver
96+
- `route_to(:collocation, value)` — route to the Collocation discretizer
97+
- `route_to(:adnlp, value)` — route to the ADNLP modeler
98+
- `route_to(:exa, value)` — route to the Exa modeler
99+
- `route_to(:ipopt, value)` — route to the Ipopt solver
100+
- `route_to(:madnlp, value)` — route to the MadNLP solver
101+
- `route_to(:uno, value)` — route to the Uno solver
102+
- `route_to(:madncl, value)` — route to the MadNCL solver
103+
- `route_to(:knitro, value)` — route to the Knitro solver
104+
105+
### Routing the same option to multiple strategies
106+
107+
You can also route the same option name to multiple strategies with different values by passing alternating strategy-value pairs:
108+
109+
```julia
110+
# Route the same option to multiple strategies with different values
111+
sol = solve(ocp, :exa, :madnlp;
112+
common_option_name=route_to(:exa, 12, :madnlp, true),
113+
max_iter=500
114+
)
115+
```
116+
117+
The syntax accepts multiple strategy-value pairs:
118+
119+
```julia
120+
route_to(strategy_id_1, val_1, strategy_id_2, val_2, ...)
121+
```
122+
123+
This is useful when:
124+
125+
- Different strategies use the same option name for different purposes
126+
- You want to configure the same option differently across strategies
127+
- You need fine-grained control over option routing
104128

105129
You can use `route_to` even for non-ambiguous options, and combine routed and non-routed options:
106130

107131
```@example advanced
108132
using MadNLP
109133
sol = solve(ocp, :madnlp;
110134
grid_size=50, # auto-routed to discretizer
111-
max_iter=route_to(madnlp=1000), # explicitly routed to solver
135+
max_iter=route_to(:madnlp, 1000), # explicitly routed to solver
112136
print_level=MadNLP.ERROR # auto-routed to solver
113137
)
114138
nothing # hide
@@ -137,7 +161,7 @@ To pass undeclared options, combine `route_to` with `bypass`:
137161
```@repl advanced
138162
sol = solve(ocp, :ipopt;
139163
max_iter=100,
140-
mumps_print_level=route_to(ipopt=bypass(1)))
164+
mumps_print_level=route_to(:ipopt, bypass(1)))
141165
```
142166

143167
You **must** combine `bypass` with `route_to` because:
@@ -146,7 +170,7 @@ You **must** combine `bypass` with `route_to` because:
146170
- `bypass` forces the option through without validation
147171

148172
!!! note "Alias: force = bypass"
149-
You can use `force` as an alias for `bypass`: `route_to(ipopt=force(1))`
173+
You can use `force` as an alias for `bypass`: `route_to(:ipopt, force(1))`
150174

151175
!!! warning "Use bypass sparingly"
152176

0 commit comments

Comments
 (0)