Skip to main content

Pyomo Conic Engine

A Python extension for Pyomo that adds support for Semidefinite Programming (SDP) and Second-Order Cone Programming (SOCP) constraints.

The library automatically decomposes affine expressions into constant and variable coefficient matrices, exporting synchronized problem files in MOSEK Conic Benchmark Format (CBF) alongside AMPL .nl bytecode and column index mappings.

Status CI Python Modeling Format License

Overview

Standard pyomo.environ does not provide native abstractions for conic constraints such as Linear Matrix Inequalities (LMIs) or second-order Lorentz cones. Handling these problems typically requires reformulating them as quadratic inequalities (which breaks conic structure) or switching to convex-only tools like CVXPY (which cannot handle non-convex polynomial terms).

pyomo-conic allows defining conic constraints directly on pyo.ConcreteModel instances:

  • Conic modeling: Add SDP matrix inequalities and SOCP cones to standard Pyomo models.
  • Affine decomposition: Extracts constant matrices and variable coefficients in a single pass without auxiliary slack variables.
  • Solver export: Writes synchronized AMPL bytecode (.nl), column order listings (.col), and Conic Benchmark Format (.cbf) files for solvers like RAPOSa, MOSEK, and Clarabel.

Quickstart

1. Second-Order Cone Programming (SOCP)

Affine expressions can be constrained to a Lorentz cone using either norm-bound component form or vector form:

import pyomo.environ as pyo
from pyomo_conic import add_socp_constraint, add_socp_cone, export_cbf_files

model = pyo.ConcreteModel()
model.x = pyo.Var([0, 1, 2], bounds=(0, None), initialize=1.0)
model.obj = pyo.Objective(expr=model.x[0] + model.x[1] + model.x[2], sense=pyo.minimize)

# Component form: 2.5 * x[0] >= sqrt( (3.0 * x[1])^2 + (1.5 * x[2])^2 )
add_socp_constraint(
    model,
    y0_expr=2.5 * model.x[0],
    y_rest_exprs=[3.0 * model.x[1], 1.5 * model.x[2]],
    name="cone_1"
)

# Vector form: [y0, y1, y2] in Q^3
add_socp_cone(
    model,
    expr_list=[2.5 * model.x[0], 3.0 * model.x[1], 1.5 * model.x[2]],
    name="cone_vector"
)

# Export solver files (.nl, .col, .cbf)
export_cbf_files(model, "output/socp_problem")

2. Semidefinite Programming (SDP / LMIs)

Linear Matrix Inequalities ($M(x) \succeq 0$) are defined as symmetric 2D lists of affine Pyomo expressions:

import pyomo.environ as pyo
from pyomo_conic import add_sdp_constraint, export_cbf_files

model = pyo.ConcreteModel()
model.x1 = pyo.Var(bounds=(0, 5), initialize=1.0)
model.x2 = pyo.Var(bounds=(0, 5), initialize=1.0)

# Define 2x2 LMI: [[ 3*x2 - 1,   x1 + x2 ],
#                 [  x1 + x2,  3*x1 - 1 ]] >= 0
matrix = [
    [3.0 * model.x2 - 1.0, model.x1 + model.x2],
    [model.x1 + model.x2,  3.0 * model.x1 - 1.0]
]

add_sdp_constraint(model, matrix=matrix, name="lmi_1")

# Export solver files (.nl, .col, .cbf)
export_cbf_files(model, "output/sdp_problem")

Mathematical Definition

The library supports two conic geometries:

1. Second-Order (Lorentz) Cone

A vector $y \in \mathbb{R}^d$ belongs to the Lorentz cone $\mathcal{Q}^d$ if and only if:

$$ \mathcal{Q}^d = \left\lbrace y \in \mathbb{R}^d \mid y_0 \ge \sqrt{\sum_{i=1}^{d-1} y_i^2}, \quad y_0 \ge 0 \right\rbrace $$

Given affine expressions $y = b + A x$, the engine extracts constant vector $b \in \mathbb{R}^d$ and coefficient matrix $A \in \mathbb{R}^{d \times n}$.

2. Semidefinite Programming (LMI)

Given a symmetric affine matrix expression $M(x) \in \mathcal{S}^n$, the Linear Matrix Inequality enforces positive semidefiniteness:

$$ M(x) = D + \sum_{t=1}^k x_t H_t \succeq 0, \quad D, H_t \in \mathcal{S}^n $$

The matrix $M(x)$ has non-negative eigenvalues for all feasible decision vectors $x$.

Format Alignment (.cbf, .col, .nl)

Calling export_cbf_files(model, "prefix") generates three synchronized files:

  1. prefix.nl: AMPL bytecode containing objective and algebraic constraints. Pyomo's export_nonlinear_variables directive ensures variables used only in conic domains are indexed without adding artificial constraints.
  2. prefix.col: Ordered list of variable names matching the 0-indexed column IDs in .nl.
  3. prefix.cbf: Conic Benchmark Format file following the MOSEK CBF v4 specification:
    • PSDCON: Defines positive semidefinite matrix cones with lower-triangular coordinates (HCOORD, DCOORD).
    • CON: Defines quadratic cones (Q) and affine coordinates (ACOORD, BCOORD).
    • SCALARCORR: Explicit mapping from CBF scalar variable indices to .nl column names.

Exporter Configuration

The export_cbf_files function provides configurable options for solver targeting and file generation:

from pyomo_conic import export_cbf_files

result = export_cbf_files(
    model,
    prefix_path="output/problem",
    export_nl=True,              # Set to False to skip AMPL bytecode generation
    export_col=True,             # Set to False to skip column mapping file
    tolerance=1e-12,             # Numerical threshold for filtering small values
    verbose=True,                # Print model summary and generated files to stdout
    symbolic_solver_labels=True  # Keyword arguments are forwarded to Pyomo writer
)

# Access paths via named attributes or tuple unpacking:
nl_path, col_path, cbf_path = result
print(result.cbf)  # "/abs/path/output/problem.cbf"
print(result.nl)   # "/abs/path/output/problem.nl" (or None if export_nl=False)
print(result.col)  # "/abs/path/output/problem.col" (or None if export_col=False)

Implementation Details

  • Single-pass traversal: Uses Pyomo's generate_standard_repn to extract affine terms in $O(N)$ time without numerical differentiation.
  • Sparse lower-triangular storage: Symmetric matrices are stored in lower-triangular coordinates ($r \ge c$) with small-value thresholding ($10^{-12}$) to keep files sparse.
  • Direct domain registration: Embeds conic bounds into the .cbf file, avoiding intermediate slack equality constraints.
  • Variable alignment: Matches variable names in the .col file with the column order in the .nl and .cbf files.

Project Structure

pyomo-conic/
├── pyomo_conic/
│   ├── __init__.py           # Package exports
│   ├── constraints.py        # Conic container, SDP/SOCP models, affine extraction
│   └── exporter.py           # CBF, NL, and COL problem exporter
├── tests/
│   ├── test_constraints.py   # Unit tests for affine extraction and validations
│   ├── test_exporter.py      # Unit tests for file generation and column ordering
│   └── test_benchmarks.py    # Integration benchmarks (SDP, SOCP, Hybrid)
├── pyproject.toml            # Build configuration and dependencies
├── requirements.txt          # Runtime requirements
├── CONTRIBUTING.md           # Contribution guidelines
├── LICENSE                   # MIT License
└── README.md                 # Project documentation

Installation and Setup

Prerequisites

  • Python 3.12+
  • Pyomo 6.10+
  • NumPy 2.5+

Installation via Pip

Install directly from GitHub into any Python environment:

pip install git+https://github.com/iago-fernandez/pyomo-conic.git

Or install from PyPI:

pip install pyomo-conic

Local Development Setup

To contribute or run tests locally:

# Clone the repository
git clone git@github.com:iago-fernandez/pyomo-conic.git
cd pyomo-conic

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in editable mode with development dependencies
pip install -e ".[dev]"

Testing

The test suite validates affine matrix decomposition, coordinate mapping, boundary conditions, and canonical benchmarks:

pytest

Research and Attribution

This library was developed as part of research engineering on RAPOSa, a global optimization solver for continuous polynomial programming.

Contributing

Please review the CONTRIBUTING guidelines for code style and development workflows.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Metadata

Release files for pyomo-conic 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyomo-conic 1.0.0
File Size Uploaded Provenance Actions
pyomo_conic-1.0.0.tar.gz 16.5 kB Without provenance Details for pyomo_conic-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyomo-conic 1.0.0
File Interpreter ABI Platform Actions
pyomo_conic-1.0.0-py3-none-any.whl Python 3 none any Details for pyomo_conic-1.0.0-py3-none-any.whl

Total release size: 27.8 kB

Release files / pyomo_conic-1.0.0.tar.gz

Download URL pyomo_conic-1.0.0.tar.gz
Size 16.5 kB
Tags Source
SHA-256 checksum
How to use checksums
33debd5428ed8bba29171064a60d948c0c4ea4649974027f9991711caee254a7
BLAKE2b-256 checksum
How to use checksums
61c57932d5294eba0da7f56f2194e39596271de11103e720af64634141a54328
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / pyomo_conic-1.0.0-py3-none-any.whl

Download URL pyomo_conic-1.0.0-py3-none-any.whl
Size 11.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b6e524218eae56598cb30452f1b7d57b3cb818808bcc5033cfc3f55b333efe45
BLAKE2b-256 checksum
How to use checksums
961a83d809dd3afaf08abaa35ad83c84c753754f81ca102221b1d4d60282aba3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for pyomo-conic 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page