Problem API

Building and solving optimization problems

Published

May 28, 2026

1 Problem

The Problem class is the main container for optimization problems.

from optyx import Problem

prob = Problem(name=None)

1.1 Parameters

Parameter	Type	Description	Default
`name`	`str \| None`	Optional problem name	`None`

2 Building Problems

2.1 Fluent API

Chain methods for concise problem definition:

from optyx import Variable, Problem

x = Variable("x", lb=0)
y = Variable("y", lb=0)

solution = (
    Problem("quadratic")
    .minimize(x**2 + y**2)
    .subject_to(x + y >= 1)
    .subject_to(x <= 5)
    .solve()
)

print(f"Objective: {solution.objective_value:.4f}")

Objective: 0.5000

2.2 Step-by-Step

Build problems incrementally:

from optyx import Variable, Problem

x = Variable("x", lb=0)
y = Variable("y", lb=0)

prob = Problem("step-by-step")
prob.minimize(x**2 + y**2)
prob.subject_to(x + y >= 1)
prob.subject_to(x <= 5)

solution = prob.solve()
print(f"Objective: {solution.objective_value:.4f}")

Objective: 0.5000

3 Methods

3.1 `.minimize(objective)`

Set a minimization objective.

prob.minimize(expr)

Parameter	Type	Description
`objective`	`Expression`	The expression to minimize

Returns: self (for chaining)

3.2 `.maximize(objective)`

Set a maximization objective.

prob.maximize(expr)

Parameter	Type	Description
`objective`	`Expression`	The expression to maximize

Returns: self (for chaining)

Note

Internally, maximization is converted to minimization by negating the objective.

3.3 `.subject_to(constraint)`

Add one or more constraints to the problem. Accepts scalar constraints, matrix-style constraints like A @ x <= b, a list of constraints, or a generator expression.

prob.subject_to(constraint)
prob.subject_to([c1, c2, c3])
prob.subject_to(x[i] >= 0 for i in range(n))  # generator
prob.subject_to(A @ x <= b)
prob.subject_to((A @ x).eq(b))

Parameter	Type	Description
`constraint`	`Constraint \\| Iterable[Constraint]`	Constraint(s) to add, including matrix blocks produced by `A @ x <= b`

Returns: self (for chaining)

Note

For dense matrices, prob.subject_to(A @ x <= b) works directly. For raw scipy.sparse matrices, wrap the matrix first with as_matrix(...). SciPy owns the left-hand @ operator for sparse matrices and tries to do a numeric multiplication before Optyx can build a symbolic MatrixVectorProduct.

as_matrix() also accepts storage="auto" | "dense" | "sparse" when you want to force or auto-select the internal storage format for large matrix blocks.

3.4 `.remove_constraint(index_or_name)`

Remove a constraint by index or name.

prob.remove_constraint(0)       # remove first constraint
prob.remove_constraint("cap")   # remove by name

Parameter	Type	Description
`index_or_name`	`int \\| str`	Index position or constraint name

Returns: self (for chaining)

Raises: IndexError if index is out of range; KeyError if name not found.

3.5 `.reset()`

Clear solver caches and warm-start state, forcing cold re-analysis on the next solve().

prob.reset()

3.6 `.write(filename)`

Export the problem to LP file format. Supports linear and quadratic objectives, constraints, variable bounds, and integer/binary sections.

prob.write("model.lp")

Parameter	Type	Description
`filename`	`str`	Output `.lp` file path

Raises: InvalidOperationError for nonlinear expressions.

3.7 `.to_lp()`

Return the LP format string (same as write() but returns the string instead of writing to a file).

lp_string = prob.to_lp()

Returns: str — the LP format representation.

3.8 Context Manager

Problem supports with statements:

with Problem() as p:
    p.minimize(x**2 + y**2)
    p.subject_to(x + y >= 1)
    solution = p.solve()

3.9 `.solve(**kwargs)`

Solve the optimization problem.

solution = prob.solve(method="auto", strict=False, warm_start=True,
                      callback=None, time_limit=None, x0=None,
                      tol=None, maxiter=None)

Parameter	Type	Description	Default
`method`	`str`	Solver method (see below)	`"auto"`
`strict`	`bool`	Raise error for unsupported features	`False`
`warm_start`	`bool`	Reuse previous solution as initial point	`True`
`callback`	`Callable[[SolverProgress], bool \\| None] \\| None`	Called each iteration; return `True` to stop	`None`
`time_limit`	`float \\| None`	Wall-clock time budget in seconds	`None`
`x0`	`np.ndarray \\| None`	Initial point	Auto-generated
`tol`	`float \\| None`	Solver tolerance	Solver default
`maxiter`	`int \\| None`	Maximum iterations	Solver default

Returns: Solution

Automatic method selection (method="auto"):

When method="auto" (default), Optyx automatically selects the best solver based on problem structure:

Problem Type	Selected Method
Linear with integer/binary variables	`milp` (HiGHS MILP solver)
Linear objective and constraints	`linprog` (HiGHS LP solver)
Unconstrained, n ≤ 3	`Nelder-Mead`
Unconstrained, n > 1000	`L-BFGS-B`
Unconstrained, else	`BFGS`
Bounds only (no general constraints)	`L-BFGS-B`
Has equality constraints	`trust-constr`
Inequality constraints only	`SLSQP`

Available methods:

Method	Bounds	Constraints	Gradient	Hessian	Description
`"auto"`	✅	✅	✅	✅	Automatic selection (default)
`"milp"`	✅	✅ (linear)	N/A	N/A	HiGHS MILP solver (integer/binary)
`"linprog"`	✅	✅ (linear)	N/A	N/A	HiGHS LP solver (for linear problems)
`"SLSQP"`	✅	✅	✅	❌	Sequential Least Squares Programming
`"trust-constr"`	✅	✅	✅	✅	Trust-region constrained optimization
`"L-BFGS-B"`	✅	❌	✅	❌	Limited-memory BFGS with bounds
`"COBYLA"`	❌	✅ (ineq)	❌	❌	Constrained Optimization BY Linear Approx
`"TNC"`	✅	❌	✅	❌	Truncated Newton Conjugate-Gradient
`"Powell"`	✅	❌	❌	❌	Powell’s conjugate direction method
`"Nelder-Mead"`	✅	❌	❌	❌	Simplex algorithm (derivative-free)
`"CG"`	❌	❌	✅	❌	Conjugate gradient
`"BFGS"`	❌	❌	✅	❌	Broyden-Fletcher-Goldfarb-Shanno
`"Newton-CG"`	❌	❌	✅	✅	Newton conjugate gradient
`"dogleg"`	❌	❌	✅	✅	Dog-leg trust-region
`"trust-ncg"`	❌	❌	✅	✅	Newton conjugate gradient trust-region
`"trust-exact"`	❌	❌	✅	✅	Nearly exact trust-region
`"trust-krylov"`	❌	❌	✅	✅	Krylov subspace trust-region

Recommended Methods

Linear problems: Use "auto" or "linprog" for best performance
With constraints: Use "SLSQP" or "trust-constr"
Bounds only: Use "L-BFGS-B" for large-scale problems
Unconstrained: Use "BFGS" or "trust-ncg" for smooth problems

Performance

LP problems: ~1.1x overhead vs raw SciPy (near parity)
CQP problems: ~1.2-2.2x overhead (with exact Jacobians)
Repeated solves: 2x-900x speedup due to caching

See the Benchmarks page for detailed performance analysis.

4 Strict Mode

Use strict=True to enforce that the solver can handle all problem features exactly:

# Strict: fail early if problem can't be solved exactly
solution = prob.solve(strict=True)  # Raises ValueError for unsupported configurations

This is useful for production code where you want to catch configurations that the solver cannot handle (e.g., nonlinear objectives with integer variables / MIQP).

5 Properties

Property	Type	Description
`.name`	`str \| None`	Problem name
`.objective`	`Expression`	Objective function
`.sense`	`str`	`"minimize"` or `"maximize"`
`.constraints`	`list[Constraint]`	All constraints
`.variables`	`list[Variable]`	All decision variables

5.1 Examples

from optyx import Variable, Problem

x = Variable("x", lb=0)
y = Variable("y", lb=0)

prob = (
    Problem("demo")
    .minimize(x**2 + y**2)
    .subject_to(x + y >= 1)
)

print(f"Name: {prob.name}")
print(f"Sense: {prob.sense}")
print(f"Variables: {[v.name for v in prob.variables]}")
print(f"Num constraints: {len(prob.constraints)}")

Name: demo
Sense: minimize
Variables: ['x', 'y']
Num constraints: 1

6 Complete Example

from optyx import Variable, Problem, exp

# Portfolio with 3 assets
w1 = Variable("stocks", lb=0, ub=0.6)
w2 = Variable("bonds", lb=0, ub=0.5)
w3 = Variable("cash", lb=0.1, ub=1.0)

# Expected returns
returns = 0.08*w1 + 0.04*w2 + 0.02*w3

# Risk (simplified variance)
risk = 0.04*w1**2 + 0.01*w2**2 + 0.001*w3**2

# Build and solve
solution = (
    Problem("portfolio")
    .minimize(risk)
    .subject_to(w1 + w2 + w3 >= 0.99)  # Fully invested
    .subject_to(w1 + w2 + w3 <= 1.01)
    .subject_to(returns >= 0.05)        # Min 5% return
    .solve()
)

print("Optimal Allocation:")
print(f"  Stocks: {solution['stocks']:.1%}")
print(f"  Bonds:  {solution['bonds']:.1%}")
print(f"  Cash:   {solution['cash']:.1%}")
print(f"Risk: {solution.objective_value:.6f}")

Optimal Allocation:
  Stocks: 34.1%
  Bonds:  46.8%
  Cash:   20.1%
Risk: 0.006873

1 Problem

1.1 Parameters

2 Building Problems

2.1 Fluent API

2.2 Step-by-Step

3 Methods

3.1 .minimize(objective)

3.2 .maximize(objective)

3.3 .subject_to(constraint)

3.4 .remove_constraint(index_or_name)

3.5 .reset()

3.6 .write(filename)

3.7 .to_lp()

3.8 Context Manager

3.9 .solve(**kwargs)

4 Strict Mode

5 Properties

5.1 Examples

6 Complete Example

3.1 `.minimize(objective)`

3.2 `.maximize(objective)`

3.3 `.subject_to(constraint)`

3.4 `.remove_constraint(index_or_name)`

3.5 `.reset()`

3.6 `.write(filename)`

3.7 `.to_lp()`

3.9 `.solve(**kwargs)`