pyoptiwize 0.2.2

Optimization tutorial: learn by example

Python Optimization Cookbook

A collection of hands-on optimization examples covering single-objective, multi-objective, constrained, and benchmark problems — implemented in Python with solvers including SciPy, pymoo, Pyomo, SCIP, IPOPT, GLPK, Optuna, and Z3.

---

📂 Package structure

pyoptiwize/                    # Package root directory
├── config/                    # Python dependency trees
└── examples/                  # Top level examples directory
    ├── bnh/py/                # Multi-objective — BNH problem (NSGA-II, Z3, PySMT)
    ├── c3dtlz4/py/            # Multi-objective optimzation benchmark problem — C3-DTLZ4 (Optuna GP Sampler)
    ├── cattlefeed/py/         # Global nonlinear constrained single objective optimization — HS73 cattle feed problem (SHGO)
    ├── constraint_dora/py/    # Constrained minimization schoolbook example (SLSQP)
    ├── deap/py/               # Constrained single-objective optimization using genetic algorithm (DEAP)
    ├── eggholder/py/          # Global unconstrained single-objective optimization — Eggholder function (SHGO, Dual Annealing)
    ├── pyomo/py/              # Solver comparison site for single- and multi-objective optimization 
    |                          # Algorithms used: large scale linear programming (GLPK)
    |                          #                  large scale non-linear optimization (IPOPT)
    |                          #                  genetic multiobjective optimization (NSGA-II and NSGA-III)
    |                          #                  mixed integer linear and non-linear programming (SCIP)
    └── shekel/py/             # Global black-box function optimization — Shekel function (SHGO)
                               # Two packages is used for building the model: Keras/TensorFlow and PyTorch

🧪 Examples

1. 🔴 BNH Problem — Multi-Objective Optimization

Path: pyoptiwize/examples/bnh/py/

Binh and Korn constrained bi-objective problem. Pareto front approximated with NSGA-II; Pareto-stable solutions certified using Z3 SMT solver and PySMT (gradient-stable and minimax-stable flavors).

• Type: Multi-objective, constrained (2 objectives, 2 constraints)
• Solvers: NSGA-II (pymoo), Z3, PySMT
• 📖 pymoo BNH

---

2. 🟣 C3-DTLZ4 — Constrained Multi-Objective Benchmark

Path: pyoptiwize/examples/c3dtlz4/py/

Scalable constrained benchmark combining DTLZ4 objectives (α=100 density bias) with C3-type constraints. Solved with Optuna's Gaussian Process Sampler.

• Type: Multi-objective, constrained, scalable (m objectives, n variables)
• Solver: Optuna GP Sampler
• 📖 Deb et al. DTLZ

---

3. 🟠 Cattle Feed Problem (HS73) — Nonlinear Programming

Path: pyoptiwize/examples/cattlefeed/py/

Hock–Schittkowski test problem #73. Minimizes a linear feed cost subject to nutritional linear, nonlinear, and equality constraints over 4 variables.

• Type: NLP, mixed linear/nonlinear constraints
• Known minimum: f(x*) ≈ 29.894
• Recommended solvers: IPOPT, SQP, interior point methods
• 📖 Reference

---

4. 🟢 Constraint Dora — Constrained Minimization

Path: pyoptiwize/examples/constraint_dora/py/

Textbook constrained minimization: minimize (x₁−2)² + (x₂−1)² subject to x₁² + x₂² ≤ 1. Solved with SLSQP; result verified analytically.

• Type: Single-objective, nonlinear constraint
• Solver: SLSQP
• 📖 WolframAlpha solution

---

5. 🟤 DEAP — Constrained Single-Objective Optimization

Path: pyoptiwize/examples/deap/py/

Production planning problem with four products (A–D) and three shared resources (labor hours, machine hours, storage space). A genetic algorithm maximises total profit subject to resource capacity, minimum production quantities, a total weight limit, and a product ratio constraint. Infeasible individuals are steered towards feasibility via a graduated penalty in the fitness function rather than outright rejection.

• Type: Single-objective, constrained
• Solver: DEAP eaSimple (generational GA — blend crossover, Gaussian mutation, tournament selection)
• 📖 Fortin et al., DEAP: Evolutionary Algorithms Made Easy, JMLR 2012 (PDF)

---

6. 🟡 Eggholder Function — Global Optimization

Path: pyoptiwize/examples/eggholder/py/

Highly non-convex 2D benchmark with many local minima. Compares SHGO and Dual Annealing; includes 3D visualization and dataset generation.

• Type: Single-objective, unconstrained, global
• Known minimum: f(x*) ≈ −959.64 at x* ≈ (512, 404.23)
• Solvers: SHGO, Dual Annealing
• 📖 Reference

---

7. 🔷 Pyomo - Solver Comparison Suite for Single Objective and Multiobjective Optimization

Path: pyoptiwize/examples/pyomo/py/

Comprehensive multi-solver comparison on the BNH problem and mixed-variable problems. Includes Pareto front approximation from CSV data using linear interpolation and decision trees, and direct solver comparisons.

• Type: Multi-objective & single-objective, constrained
• Solvers: NSGA-II, NSGA-III, SCIP, IPOPT, GLPK
• Highlights:
  • BNH Pareto front: analytical vs. linear interpolation vs. decision tree
  • Mixed-variable Pareto fronts (NSGA-II, NSGA-III)
  • Single-objective: SCIP vs. IPOPT comparison
  • Multi-objective: SCIP vs. NSGA-II comparison
  • Linear programming via GLPK

---

8. 🔵 Shekel Function — Global Optimization

Path: pyoptiwize/examples/shekel/py/

Classic 4-dimensional multimodal benchmark with 10 local minima. Solved with SciPy's SHGO algorithm using Sobol sampling.

• Type: Single-objective, unconstrained, global
• Known minimum: f(x*) ≈ −10.5363 at x* ≈ [4, 4, 4, 4]
• Solver: SHGO (Simplicial Homology Global Optimization)
• 📖 Reference

---

⚠️ Licensing limitations - please, read before installation

Please read the MathSAT 5 license terms before using MathSAT. MathSAT 5 is available for research and evaluation purposes only.
It cannot be used in a commercial environment, particularly as part of a commercial product, without written permission.
MathSAT 5 is provided as-is, without any warranty.

⚡ Installation instructions for Ubuntu 24.04

1. External dependencies

1.1 Download installation script install.bash

1.2 Review installation steps and run installation script (⚠️sudo required)

1.2.1 Installation steps:

egrep '# [1-9]\." install.bash

# 1. System packages
# 2. python3.11 and python3.13
# 3. Conda 
# 4. scip and ipopt
# 5. Mathsat
# 6. UTF-8 fonts

1.2.1 Installation command:

chmod +x install.bash && sudo ./install.bash

2. Create and enter virtual environment

2.1 python3.11

python3.11 -m venv venv_311
source venv_311/bin/activate

2.2 python3.12

python3 -m venv venv_312
source venv_312/bin/activate

2.3 python3.13

python3.13 -m venv venv_313
source venv_313/bin/activate

3. Install pyoptiwize

pip install pyoptiwize

4. Quickstart - run an example

cp -rp $(python -c 'import pyoptiwize; print(pyoptiwize.__path__[0])')/examples/eggholder .
python ./eggholder/py/optimization_ex.py

Expected results:

The first element of the sorted dataset:     512.0 404.00 -959.5797
Analytical solution [1]:                     512.0 404.23 -959.6407
Simplicial homology global optimization [2]: 512.0 404.23 -959.6407
Dual annealing [3]:                          482.4 432.88 -956.9182
Difference between SHGO and DA methods: -2.84e-01 %
[1] EGGHOLDER: https://www.sfu.ca/~ssurjano/egg.html
[2] SHGO: https://link.springer.com/article/10.1007/s10898-018-0645-y
[3] DA: https://www.jstatsoft.org/article/view/v060i06
[4] SCIPY: https://docs.scipy.org/doc/scipy/tutorial/optimize.html#global-optimization
54e5105d59a57fd2898e581ca6f1e3502d4cda22b371fa17a88420d6da862602

5. Run all examples

run_optimization_tutorial_examples [-j]

• If -j option is specified, then Jupyter server will be started

---

6. Full list of script options

run_optimization_tutorial_examples [[-h|--help] | [-clean] | [-w|--from_wheel] [-r|--force_reinstall] [-p|--python_version <version>]
                                   -h --help:             display this help message
                                   -clean:                clean all workareas /home/mdmitry/github/optimization_tutorial/bin/venv_31*
                                   -w --from_wheel:       install pyoptiwize from wheel https://pypi.org/project/pyoptiwize
                                   -r --force_reinstall:  reinstall pyoptiwize in existing workarea
                                   -p --python_version:   use python<version>
                                   -j --run_jupyter:      start jupyter notebook server
Supported python versions:            python3.11 python3.12 python3.13
Default installation:                 download git repository from the GitHub and then install from the latest version
Default python version:               python3.12
Virtual environment root directory:   $PWD/venv_31[1|2|3]

⚡ Installation instructions for Docker image

1. Installation without GUI support

docker run -it ghcr.io/mdmitry1/optimization-tutorial:latest

2. Recommended GUI support for Docker Image

2.1 Native Linux

Enter container using socat and X11 forwarding

2.2 Windows 11 with WSL2 and WSG installed

Enter container using WSLG X11 forwarding

3. Option 1: pyoptiwize package installation and running all examples in one step

bin/run_optimization_tutorial_examples [-j] [-p <python3.11|python3.13>

4. Option 2: Follow pyoptiwize instructions for Ubuntu 24.04

For example, for python3.12:

python3 -m venv venv_312
source venv_312/bin/activate
pip install pyoptiwize
run_optimization_tutorial_examples [-j]

---

🤖 AI-Powered Problem Formulator

pyoptiwize ships with an optimization problem formulator - an AI assistant that takes a plain-English description of your problem and returns a structured analysis, solver recommendation, and a ready-to-run Python script.

Recommended System Prompt

You are an optimization problem formulator assistant for the `pyoptiwize` Python package.
When the user describes an optimization problem in plain English, respond with:

1. Problem analysis -  a small table with: problem type, objectives, constraints, variables
2. Solver recommendation - the best matching pyoptiwize example and solver, with 2-3 sentences explaining why
3. Generated Python script - a complete runnable script with all imports, realistic placeholder values, under 60 lines

pyoptiwize examples available:

* `bnh/py` - multi-objective constrained, NSGA-II / Z3 / PySMT
* `c3dtlz4/py` - scalable multi-objective benchmark, Optuna GP Sampler
* `cattlefeed/py` - NLP mixed constraints single-objective, SHGO / IPOPT
* `constraint_dora/py` - single-objective nonlinear constraint, SLSQP
* `deap/py` - constrained single-objective GA, DEAP eaSimple
* `eggholder/py` - global unconstrained single-objective, SHGO / Dual Annealing
* `pyomo/py` - multi-solver comparison, NSGA-II / NSGA-III / SCIP / IPOPT / GLPK
* `shekel/py` - 4D multimodal global optimization, SHGO

Start by greeting the user and inviting them to describe their optimization problem.

Example Claude AI session

---

🛠️ Environment

Component	Version
OS	Ubuntu 24.04 LTS (Noble)
Python	3.11, 3.12, 3.13
IPOPT	3.14.19
SCIP	10.0.0
GLPK	5.0
Z3	4.8.12
PyTorch CUDA	12.8
TensorFlow CUDA	12.5.1

---

📚 References

• BNH problem — pymoo
• C3-DTLZ4 source code
• DEAP API
• Shekel function
• Eggholder function
• GLPK
• Hock & Schittkowski test problems
• IPOPT
• NSGA-II
• NSGA-III
• Optuna GP Sampler
• pymoo
• Pyomo
• PySMT
• SCIP
• SLSQP
• Z3

---

Copyright and license

© 2025-2026 Dmitry Messerman. Licensed under GNU General Public License v3.0