Skip to content

PyTorch Layers

Differentiable torch.nn.Module wrappers of the solvers, available as cupiqp.torch. See the PyTorch Layers guide for the workflow, the gradient rules and max_pending_solves.

DenseSolverLayer

DenseSolverLayer

DenseSolverLayer(
    dtype: dtype = torch.float64,
    stream: Stream | None = None,
    device: device | str | None = None,
)

Bases: SolverLayerBase

Differentiable QP layer backed by cupiqp.DenseSolver.

Solves, for one problem or a batch,

minimize    0.5 x^T P x + c^T x
subject to  A x = b
            h_l <= G x <= h_u
            x_l <= x <= x_u

with dense CUDA tensors. setup() fixes the dimensions and which blocks exist and allocates all GPU memory; every later call updates the values it is given, solves, and returns x::

layer = cupiqp.torch.DenseSolverLayer()
layer.setup(P, c, x_l=x_l, x_u=x_u)
x = layer(c=c_k)                    # solve with a new linear cost
x.sum().backward()                  # gradient for c_k

setup() takes the arguments of cupiqp.DenseSolver.setup as dense CUDA tensors of the layer dtype: each matrix is (rows, cols) or (B, rows, cols) and each vector (k,) or (B, k); the batch size is read from the batched arguments. See :class:cupiqp.DenseSolver for the meaning of every argument and for +/-inf bounds, and :class:SolverLayerBase for max_pending_solves (several solves awaiting one backward, as in a rollout).

Parameters:

Name Type Description Default
dtype dtype

torch.float32 or torch.float64, used for all data and results.

torch.float64
stream Stream

Torch stream to order the solver with. By default the layer orders itself with Torch's current stream at every call.

None
device device or str

CUDA device to solve on. Defaults to the stream's device, else Torch's current CUDA device. All tensors must live on it.

None
Source code in cupiqp/interfaces/torch/base.py
def __init__(
    self,
    dtype: torch.dtype = torch.float64,
    stream: torch.cuda.Stream | None = None,
    device: torch.device | str | None = None
) -> None:
    super().__init__()
    torch_to_warp_dtype(dtype)               # raises TypeError for any other dtype
    if stream is not None and not isinstance(stream, torch.cuda.Stream):
        raise TypeError(
            "stream must be a torch.cuda.Stream or None; got "
            f"{type(stream).__name__}."
        )
    # The device comes from, in this order: the explicit argument, the
    # stream, Torch's current CUDA device. A stream from another device
    # cannot order the solver, so the two must agree.
    resolved = None
    if device is not None:
        resolved = torch.device(device)
        if resolved.type != "cuda":
            raise ValueError(f"device must be a CUDA device; got {resolved}.")
        if resolved.index is None:
            resolved = torch.device("cuda", torch.cuda.current_device())
    if stream is not None:
        if resolved is not None and stream.device != resolved:
            raise ValueError(
                f"stream is on {stream.device} but device is {resolved}; "
                "they must agree."
            )
        resolved = stream.device
    if resolved is None:
        resolved = torch.device("cuda", torch.cuda.current_device())
    self._dtype = dtype
    self._torch_stream = stream
    self._device = resolved
    self._create_core_solver()
    self._clear_setup_state()

settings property writable

settings: Settings

Configuration of the core solver. Change fields before setup() or between calls, e.g. layer.settings.max_iter = 50. enable_grad is on by default for a layer.

result property

result: TorchSolution | None

Full solution of the latest call (duals, slacks, status) as a :class:TorchSolution, or None before the first call.

setup

setup(
    P: Tensor,
    c: Tensor,
    A: Tensor | None = None,
    b: Tensor | None = None,
    G: Tensor | None = None,
    h_u: Tensor | None = None,
    h_l: Tensor | None = None,
    x_u: Tensor | None = None,
    x_l: Tensor | None = None,
    max_pending_solves: int = 1,
    per_call_fields: Sequence[str] | None = None,
) -> None

Fix the problem structure from these tensors, load their values and allocate every GPU buffer of the layer.

Same arguments as the core solver's setup(): P and c are required; A, b (equalities), G, h_u, h_l (inequalities) and x_u, x_l (bounds) are optional. Each tensor is of the layer dtype, on the layer device, and either shared (single-problem shape) or batched (leading batch axis). The matrix format depends on the layer: dense CUDA tensors for :class:DenseSolverLayer, CUDA sparse CSR tensors for :class:SparseSolverLayer. Does not solve; call the layer afterwards. Gradients are not tracked for setup() tensors, only for those passed to the layer call.

max_pending_solves is how many differentiable calls may await their backward at once: 1 reuses the forward factorization in the backward; more saves every call's solution and refactorizes in its backward, and then requires per_call_fields, the names of the arguments every call passes. See the class documentation. Call setup() once per layer; reset() allows a new one.

Source code in cupiqp/interfaces/torch/base.py
def setup(
    self,
    P: torch.Tensor,
    c: torch.Tensor,
    A: torch.Tensor | None = None,
    b: torch.Tensor | None = None,
    G: torch.Tensor | None = None,
    h_u: torch.Tensor | None = None,
    h_l: torch.Tensor | None = None,
    x_u: torch.Tensor | None = None,
    x_l: torch.Tensor | None = None,
    max_pending_solves: int = 1,
    per_call_fields: Sequence[str] | None = None
) -> None:
    """Fix the problem structure from these tensors, load their values and
    allocate every GPU buffer of the layer.

    Same arguments as the core solver's ``setup()``: ``P`` and ``c`` are
    required; ``A, b`` (equalities), ``G, h_u, h_l`` (inequalities) and
    ``x_u, x_l`` (bounds) are optional. Each tensor is of the layer dtype,
    on the layer device, and either shared (single-problem shape) or
    batched (leading batch axis). The matrix format depends on the layer:
    dense CUDA tensors for :class:`DenseSolverLayer`, CUDA sparse CSR
    tensors for :class:`SparseSolverLayer`. Does not solve; call the
    layer afterwards. Gradients are not tracked for ``setup()`` tensors,
    only for those passed to the layer call.

    ``max_pending_solves`` is how many differentiable calls may await
    their backward at once: 1 reuses the forward factorization in the
    backward; more saves every call's solution and refactorizes in its
    backward, and then requires ``per_call_fields``, the names of the
    arguments every call passes. See the class documentation. Call
    ``setup()`` once per layer; ``reset()`` allows a new one.
    """
    inputs = dict(P=P, c=c, A=A, b=b, G=G, h_u=h_u, h_l=h_l, x_u=x_u, x_l=x_l)
    if self._is_setup:
        raise RuntimeError(
            "setup() may only be called once; call reset() before setting "
            "up a different problem."
        )
    if inputs["P"] is None or inputs["c"] is None:
        raise ValueError("Both 'P' and 'c' are required.")
    if (isinstance(max_pending_solves, bool) or not isinstance(max_pending_solves, int)
            or max_pending_solves < 1):
        raise ValueError(
            f"max_pending_solves must be a positive integer; got {max_pending_solves!r}."
        )
    per_call = None
    if max_pending_solves == 1:
        if per_call_fields is not None:
            raise ValueError(
                "per_call_fields is only used with max_pending_solves > 1, where "
                "each backward restores the data of its call; with "
                "max_pending_solves=1 leave it as None."
            )
    else:
        if not self.settings.enable_grad:
            raise ValueError("max_pending_solves > 1 requires settings.enable_grad.")
        if per_call_fields is None:
            raise ValueError(
                "max_pending_solves > 1 requires per_call_fields: the names "
                "of the arguments every call passes, e.g. ('c', 'h_u')."
            )
        per_call = frozenset(per_call_fields)
        given = self._forward_fields_given(inputs)
        unknown = sorted(n for n in per_call if n not in self._FORWARD_FIELDS)
        absent = sorted(n for n in per_call if n in self._FORWARD_FIELDS and n not in given)
        if unknown or absent:
            raise ValueError(
                f"per_call_fields must name forward() arguments given at setup(); "
                f"unknown {unknown}, not given {absent}."
            )
    core_setup_args = self._prepare_setup_inputs(inputs)
    with self._ordered_solver_stream():
        self._core_solver.setup(**core_setup_args)

    data = self._core_solver.data
    self._configured_data_fields = self._forward_fields_given(inputs)
    vector_shapes = {
        "c": (data.n,), "b": (data.p,), "h_u": (data.m,), "h_l": (data.m,),
        "x_u": (data.n,), "x_l": (data.n,),
    }
    self._unbatched_input_shapes = {
        name: (tuple(self._matrix_unbatched_shape(name)) if name in self._MATRIX_FORWARD_FIELDS
               else vector_shapes[name])
        for name in self._configured_data_fields
    }
    # Solution fields that exist for this structure. Only these are handed
    # out (absent fields are None), so no layer-owned tensor is ever an
    # autograd output that would pin a graph.
    result = self._core_solver.result
    self._solution_fields = tuple(
        name for name in SOLUTION_FIELDS if getattr(result, name).size > 0
    )
    # Everything a call or backward hands out is allocated here, once.
    if self.settings.enable_grad:
        self._shared_input_grad_buffers = {
            name: torch.empty(shape, dtype=self._dtype, device=self._device)
            for name, shape in self._unbatched_input_shapes.items()
        }
    self._max_pending_solves = max_pending_solves
    if max_pending_solves > 1:
        self._backward_state_pool = _BackwardStatePool(
            self._core_solver.result, max_pending_solves, self._dtype, self._device
        )
        self._per_call_fields = per_call
    self._is_setup = True

forward

forward(
    P: Tensor | None = None,
    c: Tensor | None = None,
    A: Tensor | None = None,
    b: Tensor | None = None,
    G: Tensor | None = None,
    h_u: Tensor | None = None,
    h_l: Tensor | None = None,
    x_u: Tensor | None = None,
    x_l: Tensor | None = None,
) -> torch.Tensor

Load the given values, solve, and return the primal solution x of shape (B, n).

Arguments left as None keep their current values. Each tensor is either shared, in the single-problem shape fixed by setup(), or batched with the leading batch axis. Gradients flow to every tensor passed here that requires them. The returned tensor is a view of the solver's result buffer, overwritten by the next call; layer.result holds the duals, slacks and the per-problem status.

Source code in cupiqp/interfaces/torch/base.py
def forward(
    self,
    P: torch.Tensor | None = None,
    c: torch.Tensor | None = None,
    A: torch.Tensor | None = None,
    b: torch.Tensor | None = None,
    G: torch.Tensor | None = None,
    h_u: torch.Tensor | None = None,
    h_l: torch.Tensor | None = None,
    x_u: torch.Tensor | None = None,
    x_l: torch.Tensor | None = None
) -> torch.Tensor:
    """Load the given values, solve, and return the primal solution ``x``
    of shape ``(B, n)``.

    Arguments left as ``None`` keep their current values. Each tensor is
    either shared, in the single-problem shape fixed by ``setup()``, or
    batched with the leading batch axis. Gradients flow to every tensor
    passed here that requires them. The returned tensor is a view of the
    solver's result buffer, overwritten by the next call; ``layer.result``
    holds the duals, slacks and the per-problem status.
    """
    return self._forward_impl((P, c, A, b, G, h_u, h_l, x_u, x_l))

reset

reset() -> None

Discard the problem and its GPU memory; setup() may then be called again, with a new structure. The settings are kept.

Refuses while a differentiable call is pending backward, since its later backward() would run on the new solver: finish that backward first, or drop the output so that its autograd graph is freed.

Source code in cupiqp/interfaces/torch/base.py
def reset(self) -> None:
    """Discard the problem and its GPU memory; ``setup()`` may then be
    called again, with a new structure. The settings are kept.

    Refuses while a differentiable call is pending backward, since its
    later ``backward()`` would run on the new solver: finish that
    backward first, or drop the output so that its autograd graph is
    freed.
    """
    # The previous result holds views of the solve's outputs and, through
    # their grad_fn, the autograd node that holds the lease. Drop it so
    # that a graph the user has already abandoned is freed now.
    self._result = None
    if self._has_active_leases():
        raise RuntimeError(
            "reset() with a differentiable solve pending backward: call "
            "backward() on its loss first, or delete the output tensors "
            "(and any loss built from them) to abandon it."
        )
    settings = self._core_solver.settings
    self._create_core_solver()
    self._core_solver.settings = settings
    self._clear_setup_state()

SparseSolverLayer

SparseSolverLayer

SparseSolverLayer(
    dtype: dtype = torch.float64,
    stream: Stream | None = None,
    device: device | str | None = None,
)

Bases: SolverLayerBase

Differentiable QP layer backed by cupiqp.SparseSolver.

Solves the same QP as :class:DenseSolverLayer with sparse P, A and G. The sparsity patterns are part of the structure: they are given once, as CUDA sparse CSR tensors, to setup(), and every later call takes only the stored values of each matrix, in the order of the CSR pattern::

layer = cupiqp.torch.SparseSolverLayer()
layer.setup(P_csr, c, A=A_csr, b=b)
x = layer(P=P_csr.values(), c=c_k)      # values only
x.sum().backward()                      # gradients for both

setup() takes P, A and G as CUDA sparse CSR tensors of the layer dtype, 2-D or 3-D with one shared pattern; store the full P (both triangles). The vectors are dense tensors, shared or batched. Values at every call are (nnz,) or (B, nnz) tensors, and their gradients have the same shape. A 3-D CSR tensor at setup() must store the same pattern for every problem; the first one is used and the others are not checked against it. Changing a pattern requires reset() and a new setup(). See :class:SolverLayerBase for max_pending_solves (several solves awaiting one backward, as in a rollout).

Parameters:

Name Type Description Default
dtype dtype

torch.float32 or torch.float64, used for all data and results.

torch.float64
stream Stream

Torch stream to order the solver with. By default the layer orders itself with Torch's current stream at every call.

None
device device or str

CUDA device to solve on. Defaults to the stream's device, else Torch's current CUDA device. All tensors must live on it.

None
Source code in cupiqp/interfaces/torch/base.py
def __init__(
    self,
    dtype: torch.dtype = torch.float64,
    stream: torch.cuda.Stream | None = None,
    device: torch.device | str | None = None
) -> None:
    super().__init__()
    torch_to_warp_dtype(dtype)               # raises TypeError for any other dtype
    if stream is not None and not isinstance(stream, torch.cuda.Stream):
        raise TypeError(
            "stream must be a torch.cuda.Stream or None; got "
            f"{type(stream).__name__}."
        )
    # The device comes from, in this order: the explicit argument, the
    # stream, Torch's current CUDA device. A stream from another device
    # cannot order the solver, so the two must agree.
    resolved = None
    if device is not None:
        resolved = torch.device(device)
        if resolved.type != "cuda":
            raise ValueError(f"device must be a CUDA device; got {resolved}.")
        if resolved.index is None:
            resolved = torch.device("cuda", torch.cuda.current_device())
    if stream is not None:
        if resolved is not None and stream.device != resolved:
            raise ValueError(
                f"stream is on {stream.device} but device is {resolved}; "
                "they must agree."
            )
        resolved = stream.device
    if resolved is None:
        resolved = torch.device("cuda", torch.cuda.current_device())
    self._dtype = dtype
    self._torch_stream = stream
    self._device = resolved
    self._create_core_solver()
    self._clear_setup_state()

settings property writable

settings: Settings

Configuration of the core solver. Change fields before setup() or between calls, e.g. layer.settings.max_iter = 50. enable_grad is on by default for a layer.

result property

result: TorchSolution | None

Full solution of the latest call (duals, slacks, status) as a :class:TorchSolution, or None before the first call.

setup

setup(
    P: Tensor,
    c: Tensor,
    A: Tensor | None = None,
    b: Tensor | None = None,
    G: Tensor | None = None,
    h_u: Tensor | None = None,
    h_l: Tensor | None = None,
    x_u: Tensor | None = None,
    x_l: Tensor | None = None,
    max_pending_solves: int = 1,
    per_call_fields: Sequence[str] | None = None,
) -> None

Fix the problem structure from these tensors, load their values and allocate every GPU buffer of the layer.

Same arguments as the core solver's setup(): P and c are required; A, b (equalities), G, h_u, h_l (inequalities) and x_u, x_l (bounds) are optional. Each tensor is of the layer dtype, on the layer device, and either shared (single-problem shape) or batched (leading batch axis). The matrix format depends on the layer: dense CUDA tensors for :class:DenseSolverLayer, CUDA sparse CSR tensors for :class:SparseSolverLayer. Does not solve; call the layer afterwards. Gradients are not tracked for setup() tensors, only for those passed to the layer call.

max_pending_solves is how many differentiable calls may await their backward at once: 1 reuses the forward factorization in the backward; more saves every call's solution and refactorizes in its backward, and then requires per_call_fields, the names of the arguments every call passes. See the class documentation. Call setup() once per layer; reset() allows a new one.

Source code in cupiqp/interfaces/torch/base.py
def setup(
    self,
    P: torch.Tensor,
    c: torch.Tensor,
    A: torch.Tensor | None = None,
    b: torch.Tensor | None = None,
    G: torch.Tensor | None = None,
    h_u: torch.Tensor | None = None,
    h_l: torch.Tensor | None = None,
    x_u: torch.Tensor | None = None,
    x_l: torch.Tensor | None = None,
    max_pending_solves: int = 1,
    per_call_fields: Sequence[str] | None = None
) -> None:
    """Fix the problem structure from these tensors, load their values and
    allocate every GPU buffer of the layer.

    Same arguments as the core solver's ``setup()``: ``P`` and ``c`` are
    required; ``A, b`` (equalities), ``G, h_u, h_l`` (inequalities) and
    ``x_u, x_l`` (bounds) are optional. Each tensor is of the layer dtype,
    on the layer device, and either shared (single-problem shape) or
    batched (leading batch axis). The matrix format depends on the layer:
    dense CUDA tensors for :class:`DenseSolverLayer`, CUDA sparse CSR
    tensors for :class:`SparseSolverLayer`. Does not solve; call the
    layer afterwards. Gradients are not tracked for ``setup()`` tensors,
    only for those passed to the layer call.

    ``max_pending_solves`` is how many differentiable calls may await
    their backward at once: 1 reuses the forward factorization in the
    backward; more saves every call's solution and refactorizes in its
    backward, and then requires ``per_call_fields``, the names of the
    arguments every call passes. See the class documentation. Call
    ``setup()`` once per layer; ``reset()`` allows a new one.
    """
    inputs = dict(P=P, c=c, A=A, b=b, G=G, h_u=h_u, h_l=h_l, x_u=x_u, x_l=x_l)
    if self._is_setup:
        raise RuntimeError(
            "setup() may only be called once; call reset() before setting "
            "up a different problem."
        )
    if inputs["P"] is None or inputs["c"] is None:
        raise ValueError("Both 'P' and 'c' are required.")
    if (isinstance(max_pending_solves, bool) or not isinstance(max_pending_solves, int)
            or max_pending_solves < 1):
        raise ValueError(
            f"max_pending_solves must be a positive integer; got {max_pending_solves!r}."
        )
    per_call = None
    if max_pending_solves == 1:
        if per_call_fields is not None:
            raise ValueError(
                "per_call_fields is only used with max_pending_solves > 1, where "
                "each backward restores the data of its call; with "
                "max_pending_solves=1 leave it as None."
            )
    else:
        if not self.settings.enable_grad:
            raise ValueError("max_pending_solves > 1 requires settings.enable_grad.")
        if per_call_fields is None:
            raise ValueError(
                "max_pending_solves > 1 requires per_call_fields: the names "
                "of the arguments every call passes, e.g. ('c', 'h_u')."
            )
        per_call = frozenset(per_call_fields)
        given = self._forward_fields_given(inputs)
        unknown = sorted(n for n in per_call if n not in self._FORWARD_FIELDS)
        absent = sorted(n for n in per_call if n in self._FORWARD_FIELDS and n not in given)
        if unknown or absent:
            raise ValueError(
                f"per_call_fields must name forward() arguments given at setup(); "
                f"unknown {unknown}, not given {absent}."
            )
    core_setup_args = self._prepare_setup_inputs(inputs)
    with self._ordered_solver_stream():
        self._core_solver.setup(**core_setup_args)

    data = self._core_solver.data
    self._configured_data_fields = self._forward_fields_given(inputs)
    vector_shapes = {
        "c": (data.n,), "b": (data.p,), "h_u": (data.m,), "h_l": (data.m,),
        "x_u": (data.n,), "x_l": (data.n,),
    }
    self._unbatched_input_shapes = {
        name: (tuple(self._matrix_unbatched_shape(name)) if name in self._MATRIX_FORWARD_FIELDS
               else vector_shapes[name])
        for name in self._configured_data_fields
    }
    # Solution fields that exist for this structure. Only these are handed
    # out (absent fields are None), so no layer-owned tensor is ever an
    # autograd output that would pin a graph.
    result = self._core_solver.result
    self._solution_fields = tuple(
        name for name in SOLUTION_FIELDS if getattr(result, name).size > 0
    )
    # Everything a call or backward hands out is allocated here, once.
    if self.settings.enable_grad:
        self._shared_input_grad_buffers = {
            name: torch.empty(shape, dtype=self._dtype, device=self._device)
            for name, shape in self._unbatched_input_shapes.items()
        }
    self._max_pending_solves = max_pending_solves
    if max_pending_solves > 1:
        self._backward_state_pool = _BackwardStatePool(
            self._core_solver.result, max_pending_solves, self._dtype, self._device
        )
        self._per_call_fields = per_call
    self._is_setup = True

forward

forward(
    P: Tensor | None = None,
    c: Tensor | None = None,
    A: Tensor | None = None,
    b: Tensor | None = None,
    G: Tensor | None = None,
    h_u: Tensor | None = None,
    h_l: Tensor | None = None,
    x_u: Tensor | None = None,
    x_l: Tensor | None = None,
) -> torch.Tensor

Load the given values, solve, and return the primal solution x of shape (B, n).

Arguments left as None keep their current values. Each tensor is either shared, in the single-problem shape fixed by setup(), or batched with the leading batch axis. Gradients flow to every tensor passed here that requires them. The returned tensor is a view of the solver's result buffer, overwritten by the next call; layer.result holds the duals, slacks and the per-problem status.

Source code in cupiqp/interfaces/torch/base.py
def forward(
    self,
    P: torch.Tensor | None = None,
    c: torch.Tensor | None = None,
    A: torch.Tensor | None = None,
    b: torch.Tensor | None = None,
    G: torch.Tensor | None = None,
    h_u: torch.Tensor | None = None,
    h_l: torch.Tensor | None = None,
    x_u: torch.Tensor | None = None,
    x_l: torch.Tensor | None = None
) -> torch.Tensor:
    """Load the given values, solve, and return the primal solution ``x``
    of shape ``(B, n)``.

    Arguments left as ``None`` keep their current values. Each tensor is
    either shared, in the single-problem shape fixed by ``setup()``, or
    batched with the leading batch axis. Gradients flow to every tensor
    passed here that requires them. The returned tensor is a view of the
    solver's result buffer, overwritten by the next call; ``layer.result``
    holds the duals, slacks and the per-problem status.
    """
    return self._forward_impl((P, c, A, b, G, h_u, h_l, x_u, x_l))

reset

reset() -> None

Discard the problem and its GPU memory; setup() may then be called again, with a new structure. The settings are kept.

Refuses while a differentiable call is pending backward, since its later backward() would run on the new solver: finish that backward first, or drop the output so that its autograd graph is freed.

Source code in cupiqp/interfaces/torch/base.py
def reset(self) -> None:
    """Discard the problem and its GPU memory; ``setup()`` may then be
    called again, with a new structure. The settings are kept.

    Refuses while a differentiable call is pending backward, since its
    later ``backward()`` would run on the new solver: finish that
    backward first, or drop the output so that its autograd graph is
    freed.
    """
    # The previous result holds views of the solve's outputs and, through
    # their grad_fn, the autograd node that holds the lease. Drop it so
    # that a graph the user has already abandoned is freed now.
    self._result = None
    if self._has_active_leases():
        raise RuntimeError(
            "reset() with a differentiable solve pending backward: call "
            "backward() on its loss first, or delete the output tensors "
            "(and any loss built from them) to abandon it."
        )
    settings = self._core_solver.settings
    self._create_core_solver()
    self._core_solver.settings = settings
    self._clear_setup_state()

MultistageSolverLayer

MultistageSolverLayer

MultistageSolverLayer(
    dtype: dtype = torch.float64,
    stream: Stream | None = None,
    device: device | str | None = None,
)

Bases: SolverLayerBase

Differentiable QP layer backed by cupiqp.MultistageSolver.

Solves the same QP as :class:DenseSolverLayer when P is block tridiagonal and A and G are block lower bidiagonal, as in optimal control over N stages of d variables (n = N*d). setup() takes the arguments of cupiqp.MultistageSolver.setup: each matrix is a (diag, offdiag) pair of CUDA tensors, and an offdiag given as None means that matrix has no coupling blocks for the lifetime of the layer::

layer = cupiqp.torch.MultistageSolverLayer()
layer.setup(P=(P_diag, None), c=c, A=(A_diag, A_offdiag), b=b,
            x_l=x_l, x_u=x_u)
x = layer(c=c_k, A_offdiag=dyn_k)   # x is (B, N*d)
x.sum().backward()                   # gradients for c_k and dyn_k

Every call takes one tensor per block, so each block can be passed, shared or batched, and differentiated on its own: P_diag (N, d, d), P_offdiag (N-1, d, d), A_diag, A_offdiag, G_diag and G_offdiag (N, r, d), each optionally with a leading batch axis. Vectors are flat, (k,) or (B, k), like the solution; a vector in block layout (N, d) is passed as c.reshape(-1), a view. A block absent at setup() cannot be passed later. per_call_fields names these call arguments, e.g. ("c", "A_offdiag"). See :class:cupiqp.MultistageSolver for the block layout and :class:SolverLayerBase for max_pending_solves.

Parameters:

Name Type Description Default
dtype dtype

torch.float32 or torch.float64, used for all data and results.

torch.float64
stream Stream

Torch stream to order the solver with. By default the layer orders itself with Torch's current stream at every call.

None
device device or str

CUDA device to solve on. Defaults to the stream's device, else Torch's current CUDA device. All tensors must live on it.

None
Source code in cupiqp/interfaces/torch/base.py
def __init__(
    self,
    dtype: torch.dtype = torch.float64,
    stream: torch.cuda.Stream | None = None,
    device: torch.device | str | None = None
) -> None:
    super().__init__()
    torch_to_warp_dtype(dtype)               # raises TypeError for any other dtype
    if stream is not None and not isinstance(stream, torch.cuda.Stream):
        raise TypeError(
            "stream must be a torch.cuda.Stream or None; got "
            f"{type(stream).__name__}."
        )
    # The device comes from, in this order: the explicit argument, the
    # stream, Torch's current CUDA device. A stream from another device
    # cannot order the solver, so the two must agree.
    resolved = None
    if device is not None:
        resolved = torch.device(device)
        if resolved.type != "cuda":
            raise ValueError(f"device must be a CUDA device; got {resolved}.")
        if resolved.index is None:
            resolved = torch.device("cuda", torch.cuda.current_device())
    if stream is not None:
        if resolved is not None and stream.device != resolved:
            raise ValueError(
                f"stream is on {stream.device} but device is {resolved}; "
                "they must agree."
            )
        resolved = stream.device
    if resolved is None:
        resolved = torch.device("cuda", torch.cuda.current_device())
    self._dtype = dtype
    self._torch_stream = stream
    self._device = resolved
    self._create_core_solver()
    self._clear_setup_state()

settings property writable

settings: Settings

Configuration of the core solver. Change fields before setup() or between calls, e.g. layer.settings.max_iter = 50. enable_grad is on by default for a layer.

result property

result: TorchSolution | None

Full solution of the latest call (duals, slacks, status) as a :class:TorchSolution, or None before the first call.

setup

setup(
    P: Tensor,
    c: Tensor,
    A: Tensor | None = None,
    b: Tensor | None = None,
    G: Tensor | None = None,
    h_u: Tensor | None = None,
    h_l: Tensor | None = None,
    x_u: Tensor | None = None,
    x_l: Tensor | None = None,
    max_pending_solves: int = 1,
    per_call_fields: Sequence[str] | None = None,
) -> None

Fix the problem structure from these tensors, load their values and allocate every GPU buffer of the layer.

Same arguments as the core solver's setup(): P and c are required; A, b (equalities), G, h_u, h_l (inequalities) and x_u, x_l (bounds) are optional. Each tensor is of the layer dtype, on the layer device, and either shared (single-problem shape) or batched (leading batch axis). The matrix format depends on the layer: dense CUDA tensors for :class:DenseSolverLayer, CUDA sparse CSR tensors for :class:SparseSolverLayer. Does not solve; call the layer afterwards. Gradients are not tracked for setup() tensors, only for those passed to the layer call.

max_pending_solves is how many differentiable calls may await their backward at once: 1 reuses the forward factorization in the backward; more saves every call's solution and refactorizes in its backward, and then requires per_call_fields, the names of the arguments every call passes. See the class documentation. Call setup() once per layer; reset() allows a new one.

Source code in cupiqp/interfaces/torch/base.py
def setup(
    self,
    P: torch.Tensor,
    c: torch.Tensor,
    A: torch.Tensor | None = None,
    b: torch.Tensor | None = None,
    G: torch.Tensor | None = None,
    h_u: torch.Tensor | None = None,
    h_l: torch.Tensor | None = None,
    x_u: torch.Tensor | None = None,
    x_l: torch.Tensor | None = None,
    max_pending_solves: int = 1,
    per_call_fields: Sequence[str] | None = None
) -> None:
    """Fix the problem structure from these tensors, load their values and
    allocate every GPU buffer of the layer.

    Same arguments as the core solver's ``setup()``: ``P`` and ``c`` are
    required; ``A, b`` (equalities), ``G, h_u, h_l`` (inequalities) and
    ``x_u, x_l`` (bounds) are optional. Each tensor is of the layer dtype,
    on the layer device, and either shared (single-problem shape) or
    batched (leading batch axis). The matrix format depends on the layer:
    dense CUDA tensors for :class:`DenseSolverLayer`, CUDA sparse CSR
    tensors for :class:`SparseSolverLayer`. Does not solve; call the
    layer afterwards. Gradients are not tracked for ``setup()`` tensors,
    only for those passed to the layer call.

    ``max_pending_solves`` is how many differentiable calls may await
    their backward at once: 1 reuses the forward factorization in the
    backward; more saves every call's solution and refactorizes in its
    backward, and then requires ``per_call_fields``, the names of the
    arguments every call passes. See the class documentation. Call
    ``setup()`` once per layer; ``reset()`` allows a new one.
    """
    inputs = dict(P=P, c=c, A=A, b=b, G=G, h_u=h_u, h_l=h_l, x_u=x_u, x_l=x_l)
    if self._is_setup:
        raise RuntimeError(
            "setup() may only be called once; call reset() before setting "
            "up a different problem."
        )
    if inputs["P"] is None or inputs["c"] is None:
        raise ValueError("Both 'P' and 'c' are required.")
    if (isinstance(max_pending_solves, bool) or not isinstance(max_pending_solves, int)
            or max_pending_solves < 1):
        raise ValueError(
            f"max_pending_solves must be a positive integer; got {max_pending_solves!r}."
        )
    per_call = None
    if max_pending_solves == 1:
        if per_call_fields is not None:
            raise ValueError(
                "per_call_fields is only used with max_pending_solves > 1, where "
                "each backward restores the data of its call; with "
                "max_pending_solves=1 leave it as None."
            )
    else:
        if not self.settings.enable_grad:
            raise ValueError("max_pending_solves > 1 requires settings.enable_grad.")
        if per_call_fields is None:
            raise ValueError(
                "max_pending_solves > 1 requires per_call_fields: the names "
                "of the arguments every call passes, e.g. ('c', 'h_u')."
            )
        per_call = frozenset(per_call_fields)
        given = self._forward_fields_given(inputs)
        unknown = sorted(n for n in per_call if n not in self._FORWARD_FIELDS)
        absent = sorted(n for n in per_call if n in self._FORWARD_FIELDS and n not in given)
        if unknown or absent:
            raise ValueError(
                f"per_call_fields must name forward() arguments given at setup(); "
                f"unknown {unknown}, not given {absent}."
            )
    core_setup_args = self._prepare_setup_inputs(inputs)
    with self._ordered_solver_stream():
        self._core_solver.setup(**core_setup_args)

    data = self._core_solver.data
    self._configured_data_fields = self._forward_fields_given(inputs)
    vector_shapes = {
        "c": (data.n,), "b": (data.p,), "h_u": (data.m,), "h_l": (data.m,),
        "x_u": (data.n,), "x_l": (data.n,),
    }
    self._unbatched_input_shapes = {
        name: (tuple(self._matrix_unbatched_shape(name)) if name in self._MATRIX_FORWARD_FIELDS
               else vector_shapes[name])
        for name in self._configured_data_fields
    }
    # Solution fields that exist for this structure. Only these are handed
    # out (absent fields are None), so no layer-owned tensor is ever an
    # autograd output that would pin a graph.
    result = self._core_solver.result
    self._solution_fields = tuple(
        name for name in SOLUTION_FIELDS if getattr(result, name).size > 0
    )
    # Everything a call or backward hands out is allocated here, once.
    if self.settings.enable_grad:
        self._shared_input_grad_buffers = {
            name: torch.empty(shape, dtype=self._dtype, device=self._device)
            for name, shape in self._unbatched_input_shapes.items()
        }
    self._max_pending_solves = max_pending_solves
    if max_pending_solves > 1:
        self._backward_state_pool = _BackwardStatePool(
            self._core_solver.result, max_pending_solves, self._dtype, self._device
        )
        self._per_call_fields = per_call
    self._is_setup = True

forward

forward(
    P_diag: Tensor | None = None,
    P_offdiag: Tensor | None = None,
    c: Tensor | None = None,
    A_diag: Tensor | None = None,
    A_offdiag: Tensor | None = None,
    b: Tensor | None = None,
    G_diag: Tensor | None = None,
    G_offdiag: Tensor | None = None,
    h_u: Tensor | None = None,
    h_l: Tensor | None = None,
    x_u: Tensor | None = None,
    x_l: Tensor | None = None,
) -> torch.Tensor

Load the given blocks and vectors, solve, and return the primal solution x of shape (B, N*d).

Arguments left as None keep their current values. Each tensor is shared, in the single-problem shape, or batched with a leading batch axis. Gradients flow to every tensor passed here that requires them. The returned tensor is overwritten by the next call (see :class:SolverLayerBase); layer.result holds the duals, slacks and the per-problem status.

Source code in cupiqp/interfaces/torch/multistage.py
def forward(
    self,
    P_diag: torch.Tensor | None = None,
    P_offdiag: torch.Tensor | None = None,
    c: torch.Tensor | None = None,
    A_diag: torch.Tensor | None = None,
    A_offdiag: torch.Tensor | None = None,
    b: torch.Tensor | None = None,
    G_diag: torch.Tensor | None = None,
    G_offdiag: torch.Tensor | None = None,
    h_u: torch.Tensor | None = None,
    h_l: torch.Tensor | None = None,
    x_u: torch.Tensor | None = None,
    x_l: torch.Tensor | None = None
) -> torch.Tensor:
    """Load the given blocks and vectors, solve, and return the primal
    solution ``x`` of shape ``(B, N*d)``.

    Arguments left as ``None`` keep their current values. Each tensor is
    shared, in the single-problem shape, or batched with a leading batch
    axis. Gradients flow to every tensor passed here that requires them.
    The returned tensor is overwritten by the next call (see
    :class:`SolverLayerBase`); ``layer.result`` holds the duals, slacks
    and the per-problem status.
    """
    return self._forward_impl((P_diag, P_offdiag, c, A_diag, A_offdiag, b,
                               G_diag, G_offdiag, h_u, h_l, x_u, x_l))

reset

reset() -> None

Discard the problem and its GPU memory; setup() may then be called again, with a new structure. The settings are kept.

Refuses while a differentiable call is pending backward, since its later backward() would run on the new solver: finish that backward first, or drop the output so that its autograd graph is freed.

Source code in cupiqp/interfaces/torch/base.py
def reset(self) -> None:
    """Discard the problem and its GPU memory; ``setup()`` may then be
    called again, with a new structure. The settings are kept.

    Refuses while a differentiable call is pending backward, since its
    later ``backward()`` would run on the new solver: finish that
    backward first, or drop the output so that its autograd graph is
    freed.
    """
    # The previous result holds views of the solve's outputs and, through
    # their grad_fn, the autograd node that holds the lease. Drop it so
    # that a graph the user has already abandoned is freed now.
    self._result = None
    if self._has_active_leases():
        raise RuntimeError(
            "reset() with a differentiable solve pending backward: call "
            "backward() on its loss first, or delete the output tensors "
            "(and any loss built from them) to abandon it."
        )
    settings = self._core_solver.settings
    self._create_core_solver()
    self._core_solver.settings = settings
    self._clear_setup_state()

TorchSolution

TorchSolution

TorchSolution(
    tensors: Mapping[str, Tensor],
    status: Tensor,
    iterations: Tensor,
    info: Info,
)

Solution of the latest call of a solver layer, as CUDA tensors.

Everything stays on the device. x has shape (B, n); the dual and slack fields are (B, k) tensors, or None when the corresponding constraint block was not given at setup(). status and iterations are int32 (B,) tensors with one entry per problem. All of them are views of the solver's buffers, written in stream order: they can be used in further Torch work on the same stream without synchronization, and the next call of the layer overwrites them. Use :meth:clone to keep a result, and .cpu() on a tensor when you need its values on the host.

info is the core solver's per-problem diagnostics (residuals, objectives, step sizes, ...) as Warp arrays on the device; its to_host() copies them all at once.

Example::

x = layer(c=c_k)
solved = layer.result.status == cupiqp.Status.CUPIQP_SOLVED  # (B,) bool, on device
if not bool(solved.all()):            # explicit host read
    print(layer.result.status.cpu())
Source code in cupiqp/interfaces/torch/types.py
def __init__(
    self,
    tensors: Mapping[str, torch.Tensor],
    status: torch.Tensor,
    iterations: torch.Tensor,
    info: Info
) -> None:
    for name in SOLUTION_FIELDS:
        setattr(self, name, tensors.get(name))
    self.status = status
    self.iterations = iterations
    self.info = info

clone

clone(*, detach: bool = False) -> TorchSolution

Return a solution whose tensors own independent storage, so that later calls of the layer do not change it. Allocates; meant for keeping a result, not for the hot path.

Source code in cupiqp/interfaces/torch/types.py
def clone(self, *, detach: bool = False) -> TorchSolution:
    """Return a solution whose tensors own independent storage, so that
    later calls of the layer do not change it. Allocates; meant for
    keeping a result, not for the hot path."""

    def copy_tensor(value: torch.Tensor | None) -> torch.Tensor | None:
        if value is None:
            return None
        if detach:
            value = value.detach()
        return value.clone()

    tensors = {
        name: copied
        for name in SOLUTION_FIELDS
        if (copied := copy_tensor(getattr(self, name))) is not None
    }
    return TorchSolution(tensors, self.status.clone(), self.iterations.clone(), self.info)

StructureMismatchError

StructureMismatchError

Bases: ValueError

A tensor passed to a layer call does not fit the structure fixed by setup(): a block that was not set up, or a shape other than the single-problem or batched shape. Call reset() and setup() again, or use another layer instance, to change the structure.