ncpolopt 0.1.0__tar.gz

ncpolopt-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ncpolopt
+Version: 0.1.0
+Summary: Sparse SDP relaxations of polynomial optimization problems with noncommuting variables (NPA hierarchy)
+Keywords: noncommutative,polynomial optimization,SDP,semidefinite programming,NPA hierarchy,quantum
+Author: ChenXu
+Author-email: ChenXu <chenxuhuang27@gmail.com>
+License-Expression: GPL-3.0-only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: sympy>=1.12
+Requires-Dist: cvxpy>=1.5 ; extra == 'all'
+Requires-Dist: mosek>=11 ; extra == 'all'
+Requires-Dist: picos>=2.4 ; extra == 'all'
+Requires-Dist: cvxopt>=1.3 ; extra == 'all'
+Requires-Dist: chompack>=2.3 ; extra == 'all'
+Requires-Dist: chompack>=2.3 ; extra == 'chordal'
+Requires-Dist: cvxopt>=1.3 ; extra == 'chordal'
+Requires-Dist: picos>=2.4 ; extra == 'cvxopt'
+Requires-Dist: cvxopt>=1.3 ; extra == 'cvxopt'
+Requires-Dist: cvxpy>=1.5 ; extra == 'cvxpy'
+Requires-Dist: mosek>=11 ; extra == 'mosek'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/ChenXu-Huang/ncpolopt
+Project-URL: Repository, https://github.com/ChenXu-Huang/ncpolopt
+Project-URL: Issues, https://github.com/ChenXu-Huang/ncpolopt/issues
+Provides-Extra: all
+Provides-Extra: chordal
+Provides-Extra: cvxopt
+Provides-Extra: cvxpy
+Provides-Extra: mosek
+Description-Content-Type: text/markdown
+
+# ncpolopt
+
+Sparse SDP relaxations of polynomial optimization problems with
+noncommuting variables — the [NPA hierarchy](https://arxiv.org/abs/0803.4291)
+and its relatives. `ncpolopt` is a modern rewrite of the GPL-3
+[ncpol2sdpa](https://github.com/peterwittek/ncpol2sdpa) package: the same
+hierarchies and the same four solver backends, behind a fresh, typed API
+built on dataclasses and lazy solver discovery.
+
+- **NPA hierarchy** for noncommutative operators, plus the
+  [Moroder](https://arxiv.org/abs/1305.2630) (PPT), steering, and RDM
+  (reduced density matrix) hierarchies.
+- **Lasserre-style hierarchies** for commuting variables, with an optional
+  chordal sparsity extension (SparsePOP-style) that splits the relaxation
+  into independent moment blocks per clique.
+- **Four solver backends**: [cvxpy](https://www.cvxpy.org/),
+  [MOSEK](https://www.mosek.com/), [PICOS/cvxopt](https://picos-api.gitlab.io/),
+  and the external [SDPA](https://sdpa.sourceforge.net/) binary — selected
+  by name or auto-detected.
+- **Moment expressions** (`MomentEntry`) instead of a string DSL for
+  writing conditions on the moment matrix directly.
+
+## Installation
+
+Requires Python 3.13+. The core package needs only numpy, scipy, and sympy;
+install a solver extra to actually solve:
+
+```bash
+uv pip install ncpolopt[cvxpy]        # or: pip install ncpolopt[cvxpy]
+```
+
+Available extras: `cvxpy`, `mosek`, `cvxopt` (PICOS + cvxopt), `chordal`
+(chompack, only needed for the chompack completion method), and `all`.
+With no solver installed the package still imports and builds relaxations;
+only solving raises a `SolverError` telling you which extra to install.
+
+## Quickstart
+
+A tiny noncommutative problem: two Hermitian operators `x0`, `x1`, minimize
+the anticommutator `x0*x1 + x1*x0` under the constraint `x1 - x1² + ½ ≥ 0`
+and the projection `x0² = x0`:
+
+```python
+import ncpolopt as nc
+
+X = nc.generate_operators("x", 2, hermitian=True)
+problem = nc.Problem(
+    X,
+    objective=X[0] * X[1] + X[1] * X[0],
+    inequalities=[-X[1] ** 2 + X[1] + 0.5],
+    substitutions={X[0] ** 2: X[0]},
+)
+solution = problem.solve(level=2)
+print(solution.primal)   # -0.75
+```
+
+## Object model
+
+Work flows through three layers, each a frozen dataclass:
+
+1. **`Problem`** — the symbolic model: variables (a list of lists for
+   multipartite problems), objective, polynomial and moment constraints,
+   substitution rules. Reusable; building a relaxation never mutates it.
+2. **`NpaRelaxation`** — the SDP at a hierarchy level, built by
+   `problem.relaxation(level)` or subclass hierarchies
+   `MoroderHierarchy`, `SteeringHierarchy`, `RdmHierarchy`. The assembled
+   SDP data (`relaxation.sdp`) is a frozen blockwise COO representation.
+3. **`Solution`** — the immutable solve result (`primal`, `dual`,
+   `status`, `x_mat`, `y_mat`) with extraction helpers:
+   `monomial_value()`, `dual_value()`, `dual_block()`,
+   `sos_decomposition()`, `solution_ranks()`.
+
+## Command line
+
+```bash
+ncpolopt                # version, platform, detected solvers
+ncpolopt --version
+```
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+GPL-3.0-only. This package is derived from ncpol2sdpa, which is
+Copyright (C) 2012-2016 Peter Wittek and contributors.

ncpolopt-0.1.0/README.md

@@ -0,0 +1,91 @@
+# ncpolopt
+
+Sparse SDP relaxations of polynomial optimization problems with
+noncommuting variables — the [NPA hierarchy](https://arxiv.org/abs/0803.4291)
+and its relatives. `ncpolopt` is a modern rewrite of the GPL-3
+[ncpol2sdpa](https://github.com/peterwittek/ncpol2sdpa) package: the same
+hierarchies and the same four solver backends, behind a fresh, typed API
+built on dataclasses and lazy solver discovery.
+
+- **NPA hierarchy** for noncommutative operators, plus the
+  [Moroder](https://arxiv.org/abs/1305.2630) (PPT), steering, and RDM
+  (reduced density matrix) hierarchies.
+- **Lasserre-style hierarchies** for commuting variables, with an optional
+  chordal sparsity extension (SparsePOP-style) that splits the relaxation
+  into independent moment blocks per clique.
+- **Four solver backends**: [cvxpy](https://www.cvxpy.org/),
+  [MOSEK](https://www.mosek.com/), [PICOS/cvxopt](https://picos-api.gitlab.io/),
+  and the external [SDPA](https://sdpa.sourceforge.net/) binary — selected
+  by name or auto-detected.
+- **Moment expressions** (`MomentEntry`) instead of a string DSL for
+  writing conditions on the moment matrix directly.
+
+## Installation
+
+Requires Python 3.13+. The core package needs only numpy, scipy, and sympy;
+install a solver extra to actually solve:
+
+```bash
+uv pip install ncpolopt[cvxpy]        # or: pip install ncpolopt[cvxpy]
+```
+
+Available extras: `cvxpy`, `mosek`, `cvxopt` (PICOS + cvxopt), `chordal`
+(chompack, only needed for the chompack completion method), and `all`.
+With no solver installed the package still imports and builds relaxations;
+only solving raises a `SolverError` telling you which extra to install.
+
+## Quickstart
+
+A tiny noncommutative problem: two Hermitian operators `x0`, `x1`, minimize
+the anticommutator `x0*x1 + x1*x0` under the constraint `x1 - x1² + ½ ≥ 0`
+and the projection `x0² = x0`:
+
+```python
+import ncpolopt as nc
+
+X = nc.generate_operators("x", 2, hermitian=True)
+problem = nc.Problem(
+    X,
+    objective=X[0] * X[1] + X[1] * X[0],
+    inequalities=[-X[1] ** 2 + X[1] + 0.5],
+    substitutions={X[0] ** 2: X[0]},
+)
+solution = problem.solve(level=2)
+print(solution.primal)   # -0.75
+```
+
+## Object model
+
+Work flows through three layers, each a frozen dataclass:
+
+1. **`Problem`** — the symbolic model: variables (a list of lists for
+   multipartite problems), objective, polynomial and moment constraints,
+   substitution rules. Reusable; building a relaxation never mutates it.
+2. **`NpaRelaxation`** — the SDP at a hierarchy level, built by
+   `problem.relaxation(level)` or subclass hierarchies
+   `MoroderHierarchy`, `SteeringHierarchy`, `RdmHierarchy`. The assembled
+   SDP data (`relaxation.sdp`) is a frozen blockwise COO representation.
+3. **`Solution`** — the immutable solve result (`primal`, `dual`,
+   `status`, `x_mat`, `y_mat`) with extraction helpers:
+   `monomial_value()`, `dual_value()`, `dual_block()`,
+   `sos_decomposition()`, `solution_ranks()`.
+
+## Command line
+
+```bash
+ncpolopt                # version, platform, detected solvers
+ncpolopt --version
+```
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+GPL-3.0-only. This package is derived from ncpol2sdpa, which is
+Copyright (C) 2012-2016 Peter Wittek and contributors.

ncpolopt-0.1.0/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "ncpolopt"
+version = "0.1.0"
+description = "Sparse SDP relaxations of polynomial optimization problems with noncommuting variables (NPA hierarchy)"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "GPL-3.0-only"
+keywords = [
+    "noncommutative",
+    "polynomial optimization",
+    "SDP",
+    "semidefinite programming",
+    "NPA hierarchy",
+    "quantum",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "sympy>=1.12",
+]
+
+[[project.authors]]
+name = "ChenXu"
+email = "chenxuhuang27@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/ChenXu-Huang/ncpolopt"
+Repository = "https://github.com/ChenXu-Huang/ncpolopt"
+Issues = "https://github.com/ChenXu-Huang/ncpolopt/issues"
+
+[project.optional-dependencies]
+cvxpy = ["cvxpy>=1.5"]
+mosek = ["mosek>=11"]
+cvxopt = [
+    "picos>=2.4",
+    "cvxopt>=1.3",
+]
+chordal = [
+    "chompack>=2.3",
+    "cvxopt>=1.3",
+]
+all = [
+    "cvxpy>=1.5",
+    "mosek>=11",
+    "picos>=2.4",
+    "cvxopt>=1.3",
+    "chompack>=2.3",
+]
+
+[project.scripts]
+ncpolopt = "ncpolopt.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "cvxpy>=1.5",
+    "mosek>=11",
+    "picos>=2.4",
+    "cvxopt>=1.3",
+    "chompack>=2.3",
+]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "C4",
+    "RUF",
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

ncpolopt-0.1.0/pyproject.toml.orig

@@ -0,0 +1,82 @@
+[project]
+name = "ncpolopt"
+version = "0.1.0"
+description = "Sparse SDP relaxations of polynomial optimization problems with noncommuting variables (NPA hierarchy)"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "GPL-3.0-only"
+authors = [
+    { name = "ChenXu", email = "chenxuhuang27@gmail.com" }
+]
+keywords = [
+    "noncommutative",
+    "polynomial optimization",
+    "SDP",
+    "semidefinite programming",
+    "NPA hierarchy",
+    "quantum",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "sympy>=1.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/ChenXu-Huang/ncpolopt"
+Repository = "https://github.com/ChenXu-Huang/ncpolopt"
+Issues = "https://github.com/ChenXu-Huang/ncpolopt/issues"
+
+[project.optional-dependencies]
+cvxpy = ["cvxpy>=1.5"]
+mosek = ["mosek>=11"]
+cvxopt = ["picos>=2.4", "cvxopt>=1.3"]
+chordal = ["chompack>=2.3", "cvxopt>=1.3"]
+all = ["cvxpy>=1.5", "mosek>=11", "picos>=2.4", "cvxopt>=1.3", "chompack>=2.3"]
+
+[project.scripts]
+ncpolopt = "ncpolopt.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "cvxpy>=1.5",
+    "mosek>=11",
+    "picos>=2.4",
+    "cvxopt>=1.3",
+    "chompack>=2.3",
+]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "C4", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

ncpolopt-0.1.0/src/ncpolopt/__init__.py

@@ -0,0 +1,98 @@
+"""ncpolopt: sparse SDP relaxations of polynomial optimization problems.
+
+Builds semidefinite programming (SDP) relaxations -- the NPA hierarchy
+for noncommuting operators, the Lasserre hierarchy for commuting
+variables -- and solves them with pluggable backends (cvxpy, MOSEK,
+cvxopt, SDPA).
+
+The package models an optimization problem as a :class:`Problem` of
+operators or variables, adds an objective and constraints, then builds a
+:class:`~ncpolopt.relaxation.NpaRelaxation` at a chosen hierarchy level
+and solves it to obtain an immutable :class:`~ncpolopt.solution.Solution`.
+
+Quickstart (a small noncommutative problem, see the README for details)::
+
+    import ncpolopt as nc
+
+    X = nc.generate_operators("x", 2, hermitian=True)
+    problem = nc.Problem(
+        X,
+        objective=X[0] * X[1] + X[1] * X[0],
+        inequalities=[-X[1] ** 2 + X[1] + 0.5],
+        substitutions={X[0] ** 2: X[0]},
+    )
+    solution = problem.solve(level=2)
+    print(solution.primal)  # -0.75
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._logging import setup_logging
+from .chordal import find_clique_index, find_variable_cliques, sliding_cliques
+from .expressions import flatten
+from .hierarchies import MoroderHierarchy, RdmHierarchy, SteeringHierarchy
+from .moment import MomentEntry, MomentExpr
+from .monomials import get_all_monomials, get_monomials
+from .physics import (
+    Probability,
+    bosonic_constraints,
+    correlator,
+    define_objective_with_I,
+    fermionic_constraints,
+    generate_measurements,
+    get_neighbors,
+    get_next_neighbors,
+    maximum_violation,
+    pauli_constraints,
+    projective_measurement_constraints,
+)
+from .problem import Problem
+from .relaxation import NpaRelaxation
+from .sdpa_writer import read_sdpa_out, write_dat_s
+from .solution import Solution
+from .solvers.base import SolverKind, SolverSettings
+from .variables import generate_operators, generate_variables, get_support
+
+try:
+    __version__ = version("ncpolopt")
+except PackageNotFoundError:  # pragma: no cover - editable installs always provide it
+    __version__ = "0.0.0"
+
+__all__ = [
+    "MomentEntry",
+    "MomentExpr",
+    "MoroderHierarchy",
+    "NpaRelaxation",
+    "Probability",
+    "Problem",
+    "RdmHierarchy",
+    "Solution",
+    "SolverKind",
+    "SolverSettings",
+    "SteeringHierarchy",
+    "__version__",
+    "bosonic_constraints",
+    "correlator",
+    "define_objective_with_I",
+    "fermionic_constraints",
+    "find_clique_index",
+    "find_variable_cliques",
+    "flatten",
+    "generate_measurements",
+    "generate_operators",
+    "generate_variables",
+    "get_all_monomials",
+    "get_monomials",
+    "get_neighbors",
+    "get_next_neighbors",
+    "get_support",
+    "maximum_violation",
+    "pauli_constraints",
+    "projective_measurement_constraints",
+    "read_sdpa_out",
+    "setup_logging",
+    "sliding_cliques",
+    "write_dat_s",
+]

ncpolopt-0.1.0/src/ncpolopt/__main__.py

@@ -0,0 +1,37 @@
+"""Command-line entry point for ncpolopt.
+
+Prints the package version, the platform it runs on, and the SDP solvers
+that are currently usable. The actual problem building happens through the
+Python API; the CLI exists so ``pip install ncpolopt`` provides a useful
+``ncpolopt`` command out of the box, and ``python -m ncpolopt`` works too.
+"""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import sys
+
+from . import __version__
+from ._logging import setup_logging
+from .solvers.registry import available_solvers
+
+
+def main() -> None:
+    """Run the CLI: report version, platform and available solvers."""
+    parser = argparse.ArgumentParser(prog="ncpolopt", description=__doc__)
+    parser.add_argument("--version", action="version", version=__version__)
+    args = parser.parse_args()  # noqa: F841 - kept for future subcommands
+    setup_logging()
+    print(f"ncpolopt {__version__}")
+    print(f"Python {platform.python_version()} on {platform.platform()}")
+    solvers = available_solvers()
+    if solvers:
+        print("Available solvers: " + ", ".join(s.name for s in solvers))
+    else:
+        print("No SDP solver found. Install one, e.g. `pip install ncpolopt[cvxpy]`.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

ncpolopt-0.1.0/src/ncpolopt/_logging.py

@@ -0,0 +1,62 @@
+"""Logging helpers shared by all ncpolopt modules.
+
+The package never prints to stdout directly; every module obtains a named
+logger through :func:`module_logger` and exposes a user-facing ``verbose``
+level that maps to standard logging severities.
+"""
+
+from __future__ import annotations
+
+import logging
+
+_LOG_LEVELS: dict[int, int] = {0: logging.WARNING, 1: logging.INFO, 2: logging.DEBUG}
+
+
+def module_logger(name: str) -> logging.Logger:
+    """Return the logger for a module, quiet by default.
+
+    The returned logger inherits the root handler configuration; call
+    :func:`setup_logging` once from an entry point to enable output.
+
+    Args:
+        name: The ``__name__`` of the calling module.
+
+    Returns:
+        A logger that only emits warnings unless the package is configured
+        for verbose output.
+    """
+    return logging.getLogger(name)
+
+
+def verbosity_to_level(verbose: int) -> int:
+    """Map the package's ``verbose`` integer to a logging severity.
+
+    Args:
+        verbose: 0 (warnings only), 1 (info) or 2 (debug). Higher values
+            are clamped to debug.
+
+    Returns:
+        The matching ``logging`` level constant.
+    """
+    return _LOG_LEVELS.get(verbose, logging.DEBUG)
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    """Configure the root logger with a console handler.
+
+    Idempotent: calling it repeatedly does not stack duplicate handlers.
+    The handler carries the ``"ncpolopt"`` name so tests (and the function
+    itself) can recognize and detach it.
+
+    Args:
+        level: The logging severity to emit, e.g. ``logging.INFO``.
+    """
+    root = logging.getLogger()
+    root.setLevel(level)
+    for handler in root.handlers:
+        if getattr(handler, "name", None) == "ncpolopt":
+            return
+    handler = logging.StreamHandler()
+    handler.name = "ncpolopt"
+    handler.setFormatter(logging.Formatter("%(levelname)s:%(name)s: %(message)s"))
+    root.addHandler(handler)