sdplab 0.0.1__py3-none-any.whl

sdplab/__init__.py

@@ -0,0 +1,115 @@
+# Copyright 2026 Pavlo Pelikh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""Semidefinite and conic programs over spacecore Euclidean Jordan algebras.
+
+.. math::
+
+    \min_X \quad \langle C, X\rangle
+    \quad \text{s.t.} \quad \mathcal{A}X = b,\quad X \succeq 0
+
+``X`` is any Jordan-algebra element -- Hermitian matrix, nonnegative vector, or
+a tree of such blocks -- and :math:`X \succeq 0` means a nonnegative spectrum.
+Build with ``SDPProblem(C, A, b)``; solve with :func:`run_cvxpy_solver`, or
+smooth it: a :class:`Regularizer` through
+:class:`RegularizedSDPDualFunctional`, ``.bind(eps)``, then
+:func:`run_regularized_solver`.
+
+Smoothing adds :math:`\varepsilon \operatorname{Tr}[\varphi(X)]` to the primal,
+giving the differentiable dual
+
+.. math::
+
+    D_\varepsilon(y) = \langle b, y\rangle - \varepsilon
+      \operatorname{Tr}\!\big[\psi\big(
+      (\mathcal{A}^\dagger y - C)/\varepsilon\big)\big],
+
+maximized over ``y`` in ``cod``, with :math:`\psi'` of the dual slack
+recovering the primal. :math:`\varepsilon` is per-call, so continuation needs
+no rebuild.
+
+Subpackages: :mod:`~sdplab.problem`, :mod:`~sdplab.regularization`,
+:mod:`~sdplab.solvers`, :mod:`~sdplab.examples`, :mod:`~sdplab.linalg`,
+:mod:`~sdplab.special`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .problem import (
+    ConstraintOp,
+    Cost,
+    DenseConstraintOp,
+    MatrixFreeConstraintOp,
+    SDPProblem,
+    SparseConstraintOp,
+)
+from .regularization import (
+    BoundDualFunctional,
+    EntropyReg,
+    QuadraticReg,
+    RegularizedSDPDualFunctional,
+    Regularizer,
+)
+from ._version import __version__
+
+# Solvers pull in CVXPY (~1.2s), making an optional backend a hard requirement
+# for anyone who only builds problems. PEP 562 keeps them reachable as
+# ``sdplab.run_*`` while deferring the cost to first use.
+_LAZY = {
+    "run_regularized_solver": "sdplab.solvers",
+    "run_cvxpy_solver": "sdplab.solvers",
+}
+
+if TYPE_CHECKING:  # type checkers and IDEs do not run __getattr__
+    from .solvers import run_cvxpy_solver, run_regularized_solver
+
+
+def __getattr__(name: str):
+    """Resolve the lazily-exported solver entry points on first access."""
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value          # cache, so this runs once per name
+    return value
+
+
+def __dir__() -> list[str]:
+    """Include the lazy names in ``dir(sdplab)`` and tab completion."""
+    return sorted(set(globals()) | set(_LAZY))
+
+
+__all__ = [
+    "__version__",
+    # problem data
+    "SDPProblem",
+    "Cost",
+    "ConstraintOp",
+    "DenseConstraintOp",
+    "SparseConstraintOp",
+    "MatrixFreeConstraintOp",
+    # regularization and the smoothed dual
+    "Regularizer",
+    "EntropyReg",
+    "QuadraticReg",
+    "RegularizedSDPDualFunctional",
+    "BoundDualFunctional",
+    # solvers (lazy)
+    "run_regularized_solver",
+    "run_cvxpy_solver",
+]

sdplab/_version.py

@@ -0,0 +1,17 @@
+# Copyright 2026 Pavlo Pelikh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Single source of truth for the SDPLab package version."""
+
+__version__ = "0.0.1"

sdplab/examples/__init__.py

@@ -0,0 +1,56 @@
+# Copyright 2026 Pavlo Pelikh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""Ready-made SDP instances for testing and benchmarking.
+
+Each builder returns a :class:`~sdplab.problem.SDPProblem`; they differ in the
+structure of :math:`\mathcal{A}`.
+
+``generate_max_cut``
+    Diagonal extraction, :math:`\operatorname{Herm}(n) \to \mathbb{R}^n`. Real,
+    and **gauge-degenerate**: :math:`\mathcal{A}^\dagger \mathbf{1} = \mathbb{1}`,
+    so the dual is fixed only modulo :math:`\operatorname{span}\{\mathbf 1\}`.
+``generate_random_qot``
+    One-body partial traces,
+    :math:`\operatorname{Herm}(d^N) \to \operatorname{Herm}(d)^N`. Complex,
+    stacked-block codomain. Returns ``(problem, state)``, ``state`` feasible.
+``generate_qubit_tomography``
+    :math:`\operatorname{Tr}[M_i X] = b_i` plus a unit-trace row. Zero cost, so
+    pure feasibility.
+
+All three domains are :class:`~spacecore.HermitianSpace`, but the interfaces
+are written against the general Euclidean Jordan algebra contract -- orthant
+spaces, block products, trees mixing cone types. Prefer space-level operations
+(``spectrum``, ``flatten``, ``axpy``) over anything assuming a dense block.
+"""
+
+from ._max_cut import (
+    MaxCutOperator,
+    generate_erdos_renyi_graph_laplacian,
+    generate_max_cut,
+)
+from .q_tomography import generate_qubit_tomography
+from .qot import QOTConstraintOp, generate_random_qot
+
+__all__ = [
+    # problem generators
+    "generate_max_cut",
+    "generate_qubit_tomography",
+    "generate_random_qot",
+    # constraint operators, for hand-assembled instances
+    "MaxCutOperator",
+    "QOTConstraintOp",
+    # supporting utilities
+    "generate_erdos_renyi_graph_laplacian",
+]

sdplab/examples/_max_cut.py

@@ -0,0 +1,168 @@
+# Copyright 2026 Pavlo Pelikh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import numpy as np
+from spacecore import (
+    Context,
+    DenseArray,
+    DenseVectorSpace,
+    HermitianSpace,
+    LinOp,
+    NumpyOps,
+    checked_method,
+    jax_pytree_class,
+)
+
+from sdplab.problem import SDPProblem
+
+
+@jax_pytree_class
+class MaxCutOperator(LinOp[HermitianSpace, DenseVectorSpace]):
+    r"""Diagonal-extraction operator :math:`\mathcal{A}` for the Max-Cut SDP.
+
+    The linear map is
+    :math:`\mathcal{A}: \operatorname{Herm}(n) \to \mathbb{R}^n` with
+    :math:`(\mathcal{A}X)_i = X_{ii}`, so the constraint
+    :math:`\mathcal{A}X = \mathbf{1}` fixes every diagonal entry to one. Its
+    adjoint sends a vector to the matrix with that diagonal,
+    :math:`\mathcal{A}^\dagger y = \operatorname{diag}(y)`, which satisfies
+    :math:`\operatorname{Tr}[(\mathcal{A}X)y] = \operatorname{Tr}[X \operatorname{diag}(y)]`.
+    """
+
+    @checked_method(in_space="domain", out_space="codomain")
+    def apply(self, X: DenseArray) -> DenseArray:
+        r"""Return :math:`\mathcal{A}X = \operatorname{diag}(X)`, the diagonal of ``X``."""
+        return self.ops.diag(X)
+
+    @checked_method(in_space="codomain", out_space="domain")
+    def rapply(self, y: DenseArray) -> DenseArray:
+        r"""Return :math:`\mathcal{A}^\dagger y = \operatorname{diag}(y)`."""
+        return self.ops.diag(y)
+
+    def to_dense(self) -> DenseArray:
+        r"""Return the operator tensor of shape ``codomain.shape + domain.shape``.
+
+        The entry ``T[i, p, q]`` is one iff ``i == p == q``, so that
+        ``sum_{p,q} T[i, p, q] X[p, q] = X[i, i]``.
+        """
+        n = self.cod.shape[0]
+        idx = self.ops.arange(n)
+        mask = (idx[:, None, None] == idx[None, :, None]) & (
+            idx[:, None, None] == idx[None, None, :]
+        )
+        return self.ops.asarray(mask, dtype=self.dtype)
+
+    def tree_flatten(self):
+        """The operator carries no arrays; spaces and context are static aux."""
+        return (), (self.dom, self.cod, self.ctx)
+
+    @classmethod
+    def tree_unflatten(cls, aux, children):
+        """Rebuild the operator from JAX PyTree data."""
+        dom, cod, ctx = aux
+        return cls(dom, cod, ctx)
+
+    def _convert(self, new_ctx: Context) -> MaxCutOperator:
+        """Return an equivalent operator in ``new_ctx``."""
+        return MaxCutOperator(self.dom.convert(new_ctx), self.cod.convert(new_ctx), new_ctx)
+
+
+def generate_erdos_renyi_graph_laplacian(
+    n: int,
+    p: float = 0.3,
+    seed: int | None = None,
+    weighted: bool = True,
+    weight_low: float = 0.0,
+    weight_high: float = 1.0,
+) -> np.ndarray:
+    """
+    Generate an undirected Erdős–Rényi graph G(n, p).
+
+    Returns
+    -------
+    L:
+        Graph Laplacian L = D - W in S^n,
+        where D[i, i] = sum_j W[i, j].
+    """
+    if n <= 0:
+        raise ValueError("n must be positive.")
+    if not (0.0 <= p <= 1.0):
+        raise ValueError("p must be in [0, 1].")
+    if weight_low < 0 or weight_high < weight_low:
+        raise ValueError("Require 0 <= weight_low <= weight_high.")
+
+    rng = np.random.default_rng(seed)
+
+    # Upper-triangular edge mask, excluding diagonal.
+    edge_mask = rng.random((n, n)) < p
+    edge_mask = np.triu(edge_mask, k=1)
+
+    if weighted:
+        weights = rng.uniform(weight_low, weight_high, size=(n, n))
+        W_upper = edge_mask * weights
+    else:
+        W_upper = edge_mask.astype(float)
+
+    W = W_upper + W_upper.T
+
+    degrees = W.sum(axis=1)
+    L = np.diag(degrees) - W
+
+    return L
+
+
+def generate_max_cut(
+    n: int,
+    p: float = 0.3,
+    seed: int | None = None,
+    weighted: bool = True,
+    weight_low: float = 0.0,
+    weight_high: float = 1.0,
+    atol: float = 0.0,
+    rtol: float = 0.0,
+    enforce_herm: bool = True,
+    unit_trace: bool = False,
+    ctx: Context | str | None = None
+):
+    r"""Return the Max-Cut SDP for an Erdős–Rényi graph on ``n`` vertices.
+
+    The constraint is :math:`\operatorname{diag}(X) = \mathbf{1}`, hence
+    :math:`\operatorname{Tr}X = n`. With ``unit_trace=True`` the substitution
+    :math:`X = n\tilde X` is applied instead, giving
+    :math:`\operatorname{diag}(\tilde X) = \mathbf{1}/n`,
+    :math:`\operatorname{Tr}\tilde X = 1`, and cost :math:`nC` -- the same
+    problem in a rescaled variable, so the optimal value is unchanged. Use it
+    when a unit-trace primal is assumed, as by the fixed-trace (log-partition)
+    form of the entropy dual.
+    """
+    np_ctx = Context(NumpyOps(), dtype="float64", check_level="none")
+
+    L = generate_erdos_renyi_graph_laplacian(n, p, seed, weighted, weight_low, weight_high)
+    C = -L / 4  # Minus to turn maximization into minimization
+    b = np.ones(n)
+    if unit_trace:
+        C = C * n
+        b = b / n
+
+    dom = HermitianSpace(n, atol=atol, rtol=rtol, enforce_herm=enforce_herm, ctx=np_ctx)
+    cod = DenseVectorSpace((n,), ctx=np_ctx)
+    A = MaxCutOperator(dom, cod, np_ctx)
+
+    sdp = SDPProblem(C, A, b, ctx=np_ctx)
+
+    if ctx is not None:
+        sdp = sdp.convert(ctx)
+    return sdp

sdplab/examples/q_tomography/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2026 Pavlo Pelikh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""State tomography as feasibility: find :math:`X \succeq 0` with
+:math:`\operatorname{Tr}[M_i X] = b_i` and :math:`\operatorname{Tr}[X] = 1`.
+
+Unit trace is appended as one more measurement row. See :mod:`._build` for the
+transpose the dense operator needs.
+"""
+
+from ._build import generate_qubit_tomography
+
+__all__ = ["generate_qubit_tomography"]

sdplab/examples/q_tomography/_build.py

@@ -0,0 +1,130 @@
+# Copyright 2026 Pavlo Pelikh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""Builders for qubit tomography SDP feasibility problems.
+
+Quantum tomography estimates an unknown density matrix
+:math:`X \in \operatorname{Herm}(d)` from linear measurement constraints.
+This module builds the feasibility SDP
+
+.. math::
+
+    \min_{X \in \operatorname{Herm}(d)}\quad 0
+    \quad \text{s.t.} \quad
+    \mathcal{A}X = b_{\mathrm{obs}},\quad
+    \operatorname{Tr}[X] = 1,\quad
+    X \succeq 0.
+
+Here :math:`\mathcal{A}: \operatorname{Herm}(d) \to \mathbb{R}^m` is the
+measurement map :math:`(\mathcal{A}X)_i = \operatorname{Tr}[M_i X]` and
+:math:`b_{\mathrm{obs}}` stores the observed expectation values. The unit-trace
+constraint is appended as one extra row measuring the identity, so the returned
+object is a plain :class:`~sdplab.problem.SDPProblem`.
+
+The measurement map is a dense tensor contraction and nothing more, so it is a
+:class:`~sdplab.problem.DenseConstraintOp` rather than a hand-written operator
+-- see the transpose note on :func:`generate_qubit_tomography`.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from spacecore import Context, DenseArray, DenseVectorSpace, HermitianSpace, NumpyOps
+
+from ...problem import DenseConstraintOp, SDPProblem
+
+
+def generate_qubit_tomography(
+    M: DenseArray,
+    b_obs: DenseArray,
+    atol: float = 0.0,
+    rtol: float = 0.0,
+    enforce_herm: bool = True,
+    ctx: Context | str | None = None,
+) -> SDPProblem:
+    r"""Build the tomography feasibility SDP for observables ``M``.
+
+    The unknown is a density matrix :math:`X \in \operatorname{Herm}(d)` and
+    the returned problem is
+
+    .. math::
+
+        \min_{X \in \operatorname{Herm}(d)}\quad 0
+        \quad \text{s.t.} \quad
+        \operatorname{Tr}[M_i X] = b_i,\quad
+        \operatorname{Tr}[X] = 1,\quad
+        X \succeq 0.
+
+    The trace-one constraint is appended as one extra row measuring the
+    identity, so the constraint operator has ``m + 1`` rows.
+
+    **Mind the transpose.** A :class:`~sdplab.problem.DenseConstraintOp` pairs
+    its tensor with :math:`X` by Frobenius,
+    :math:`(\mathcal{A}X)_i = \sum_{pq} T_{i,pq} X_{pq} =
+    \operatorname{Tr}[T_i^{T} X]`. Handing it the observables directly would
+    therefore measure :math:`\operatorname{Tr}[M_i^{T} X]` -- for a Hermitian
+    observable the *conjugate* of the intended value, silently flipping the
+    sign of every measurement with a nonzero imaginary part (the Pauli
+    :math:`Y`, say). The stack is transposed here so that
+    :math:`(\mathcal{A}X)_i = \operatorname{Tr}[M_i X]`, which also makes the
+    operator's cvxpy encoding come out as the :math:`M_i` themselves.
+
+    Args:
+        M: Stack of Hermitian observables, shape ``(m, d, d)``.
+        b_obs: Observed expectation values :math:`b_i = \operatorname{Tr}[M_i X]`,
+            length ``m``. Taken as real -- an imaginary part would not be
+            attainable by a Hermitian observable on a Hermitian state.
+        atol: Absolute Hermitian membership tolerance.
+        rtol: Relative Hermitian membership tolerance.
+        enforce_herm: Whether the primal domain enforces Hermitian matrices.
+        ctx: Optional backend context for the returned problem. The problem is
+            assembled on NumPy (in a complex dtype when ``M`` is complex) and
+            converted, matching :func:`~sdplab.examples.generate_max_cut`.
+
+    Returns:
+        Feasibility :class:`~sdplab.problem.SDPProblem` with a zero cost.
+
+    Raises:
+        ValueError: If ``M`` is not a stack of square matrices, if ``b_obs``
+            does not match its length, or if any observable is not Hermitian.
+    """
+    M = np.asarray(M)
+    b_obs = np.asarray(b_obs).reshape(-1)
+
+    if M.ndim != 3 or M.shape[-1] != M.shape[-2]:
+        raise ValueError(f"M must have shape (m, d, d); got {M.shape}.")
+    if b_obs.shape[0] != M.shape[0]:
+        raise ValueError(
+            f"b_obs has length {b_obs.shape[0]}, but M has {M.shape[0]} observables."
+        )
+    if not np.allclose(M, np.conj(np.swapaxes(M, -1, -2)), atol=1e-10):
+        raise ValueError("every observable M[i] must be Hermitian.")
+
+    m, d = M.shape[0], M.shape[-1]
+    dtype = "complex128" if np.iscomplexobj(M) else "float64"
+    np_ctx = Context(NumpyOps(), dtype=dtype, check_level="none")
+
+    # Append Tr[X] = 1 as one extra measurement of the identity.
+    M_full = np.concatenate([M.astype(dtype), np.eye(d, dtype=dtype)[None]], axis=0)
+    b_full = np.concatenate([b_obs.real.astype("float64"), [1.0]])
+
+    dom = HermitianSpace(d, atol=atol, rtol=rtol, enforce_herm=enforce_herm, ctx=np_ctx)
+    cod = DenseVectorSpace((m + 1,), ctx=np_ctx)
+    A = DenseConstraintOp(np.swapaxes(M_full, -1, -2), dom, cod, np_ctx)
+
+    sdp = SDPProblem(dom.zeros(), A, b_full, ctx=np_ctx)   # zero cost: pure feasibility
+
+    if ctx is not None:
+        sdp = sdp.convert(ctx)
+    return sdp

sdplab/examples/qot/__init__.py

@@ -0,0 +1,31 @@
+# Copyright 2026 Pavlo Pelikh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""Random quantum optimal-transport instances: a coupling
+:math:`\Gamma \in \operatorname{Herm}(d^N)` of minimal cost with prescribed
+one-body marginals :math:`\operatorname{Tr}^k[\Gamma] = \gamma_k`.
+
+The codomain is a stack of Hermitian blocks, so the dual is a tuple of matrices
+rather than a vector of scalars. :func:`generate_random_qot` derives the
+marginals from a reference coupling, so the returned ``(problem, state)``
+carries a feasible point.
+"""
+
+from ...special.qot import QOTConstraintOp
+from ._random import generate_random_qot
+
+__all__ = [
+    "QOTConstraintOp",
+    "generate_random_qot",
+]

sdplab/examples/qot/_random.py

@@ -0,0 +1,132 @@
+# Copyright 2026 Pavlo Pelikh
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""Random QOT problem generator.
+
+Use this module when you want a self-contained QOT test problem. It creates a
+random cost matrix, builds a valid primal density matrix, computes the
+marginals from that density matrix, and returns an SDP whose constraints are
+therefore feasible by construction.
+"""
+
+from typing import Any, Optional, Tuple
+import numpy as np
+
+from spacecore import Context, NumpyOps
+from ...special.qot import QOTConstraintOp
+from ...problem import SDPProblem
+
+
+def generate_random_qot(
+        d: int, N: int,
+        proportions: tuple[float, ...],
+        seed: Optional[int] = 0,
+        atol: float = 0.0,
+        rtol: float = 0.0,
+        enforce_herm: bool = True,
+        ctx: Context | str | None = None
+) -> Tuple[SDPProblem, Any]:
+    r"""
+    Generate a random dense QOT instance together with a feasible primal state.
+
+    The generated SDP has the form
+
+    .. math::
+
+        \min_\Gamma \quad \operatorname{Tr}[C \Gamma]
+        \quad \text{s.t.} \quad
+        \operatorname{Tr}^k[\Gamma] = \gamma_k,\quad
+        k = 0, ..., N - 1,\quad \Gamma \succeq 0.
+
+    The function first chooses a reference coupling ``Gamma`` and then defines
+    :math:`\gamma_k = \operatorname{Tr}^k[\Gamma]`. Because the right-hand side is computed
+    from ``Gamma``, the returned ``state`` is guaranteed to satisfy the
+    equality constraints.
+
+    This function samples a random Hermitian cost matrix on
+    :math:`(\mathbb{C}^d)^{\otimes N}`,
+    builds a reference density matrix as a convex combination of eigenvector projectors,
+    computes its one-body marginals through ``QOTConstraintOp``, and returns the
+    corresponding dense SDP problem plus the same state as a plain ``dom`` element.
+
+    The generated primal state is feasible for the constructed constraint data by design,
+    since the marginals are obtained by applying the constraint operator to that state.
+
+    Args:
+        d: Local Hilbert space dimension. The full state space is
+            :math:`(\mathbb{C}^d)^{\otimes N}`, so the ambient matrix size is
+            :math:`D = d^N`.
+        N: Number of subsystems.
+        proportions: Coefficients used to form the mixed state
+            :math:`\Gamma = \sum_i p_i \, |v_i\rangle \langle v_i|`,
+            where the :math:`v_i` are eigenvectors of the sampled cost matrix.
+            This is intended to be a convex combination, so the entries should
+            be nonnegative and sum to :math:`1`.
+        seed: Random seed used for NumPy sampling.
+        atol: Absolute tolerance passed to ``QOTConstraintOp``.
+        rtol: Relative tolerance passed to ``QOTConstraintOp``.
+        enforce_herm: Whether the constraint operator should enforce Hermitian outputs.
+        ctx: Target context for the returned SDP problem. If provided, the generated
+            problem is converted to this context before returning.
+
+    Returns:
+        - ``qot`` is an ``SDPProblem`` representing the dense QOT SDP with the
+          sampled Hermitian cost matrix and marginals induced by ``Gamma``.
+        - ``state`` is the same density matrix used to define the marginals, a
+          plain ``dom`` element in the returned problem's context.
+
+    Notes:
+        - The random cost matrix is sampled entrywise in real and imaginary parts and
+          then symmetrized to be Hermitian.
+        - The density matrix ``Gamma`` is built in the NumPy complex context
+          ``Context(NumpyOps(), dtype=np.complex128)`` before optional conversion.
+    """
+
+    D = d ** N
+
+    proportions = np.asarray(proportions, dtype=float)
+
+    if len(proportions) > D:
+        raise ValueError("len(proportions) cannot exceed D = d ** N")
+
+    if np.any(proportions < 0):
+        raise ValueError("proportions must be nonnegative")
+
+    if not np.isclose(np.sum(proportions), 1.0):
+        raise ValueError("proportions must sum to 1")
+
+    rng = np.random.default_rng(seed)
+    cost_re_im = rng.normal(size=(2, D, D))
+    cost_matrix = cost_re_im[0, :, :] + 1j * cost_re_im[1, :, :]
+    cost_matrix = (cost_matrix + cost_matrix.T.conj()) * .5
+
+    # Compute eigenvalues and eigenvectors
+    evals, evecs = np.linalg.eigh(cost_matrix)
+
+    # Compute ground state energy and density matrix
+    np_ctx = Context(NumpyOps(), dtype=np.complex128, check_level="none")
+    Gamma = sum(p * np.outer(v, v.conj()) for p, v in zip(proportions, evecs.T))
+    Gamma = (Gamma + Gamma.T.conj()) * .5
+    qot_op = QOTConstraintOp(d=d, N=N, atol=atol, rtol=rtol, enforce_herm=enforce_herm, ctx=np_ctx)
+    marginals = qot_op.apply(Gamma)
+
+    # Define QOT problem & convert to target ctx
+    qot = SDPProblem(cost_matrix, qot_op, marginals, ctx=np_ctx)
+    if ctx is not None:
+        qot = qot.convert(ctx)
+
+    # Move the example state onto the problem's context
+    state = qot.ctx.asarray(Gamma)
+
+    return qot, state