pyvallocation.utils.constraints Module

class pyvallocation.utils.constraints.Constraints(long_only=True, total_weight=1.0, bounds=None, relative_bounds=None, group_constraints=None, additional_G_h=None, additional_A_b=None)[source]

Bases: object

Typed, immutable constraint specification for portfolio optimisers.

All fields have sensible defaults so that Constraints() produces a long-only, fully-invested constraint set.

Examples

>>> c = Constraints()                          # long-only, sum=1
>>> c = Constraints(bounds=(0.0, 0.3))         # per-asset cap at 30%
>>> c = Constraints(group_constraints={
...     "Equity": ([0, 1, 2], 0.2, 0.6),      # 20-60% in equities
... })
>>> c = Constraints.from_dict({"long_only": True, "total_weight": 1.0})

Parameters:

long_only (bool)
total_weight (int | float | None)
bounds (Tuple[int | float, int | float] | Sequence[Tuple[int | float, int | float]] | Dict[int, Tuple[int | float, int | float]] | None)
relative_bounds (Sequence[Tuple[int, int, int | float]] | None)
group_constraints (Dict[str, Tuple[Sequence[int], int | float, int | float]] | None)
additional_G_h (Sequence[Tuple[Sequence[int | float], int | float]] | None)
additional_A_b (Sequence[Tuple[Sequence[int | float], int | float]] | None)

additional_A_b: Sequence[Tuple[Sequence[int | float], int | float]] | None = None

additional_G_h: Sequence[Tuple[Sequence[int | float], int | float]] | None = None

bounds: Tuple[int | float, int | float] | Sequence[Tuple[int | float, int | float]] | Dict[int, Tuple[int | float, int | float]] | None = None

classmethod from_dict(d)[source]

Create a Constraints instance from a dictionary.

Unrecognised keys are silently ignored for backward compatibility.

Parameters:: d (Dict[str, Any])
Return type:: Constraints

group_constraints: Dict[str, Tuple[Sequence[int], int | float, int | float]] | None = None

long_only: bool = True

relative_bounds: Sequence[Tuple[int, int, int | float]] | None = None

to_matrices(n_assets)[source]

Build CVXOPT-compatible (G, h, A, b) constraint matrices.

Parameters:: n_assets – Number of portfolio assets.
Returns:: Tuple of (G, h, A, b) arrays or None.
Parameters:: n_assets (int)
Return type:: Tuple[numpy.ndarray | None, numpy.ndarray | None, numpy.ndarray | None, numpy.ndarray | None]

total_weight: int | float | None = 1.0

pyvallocation.utils.constraints.build_G_h_A_b(n_assets, *, total_weight=1.0, long_only=True, bounds=None, relative_bounds=None, group_constraints=None, additional_G_h=None, additional_A_b=None, return_none_if_empty=True)[source]

Assemble inequality and equality constraints for portfolio optimisers.

The helper converts high-level constraint specifications (long-only, box bounds, pairwise relative bounds, and custom rows) into the G, h, A and b matrices expected by CVXOPT-based solvers.

Parameters:

n_assets – Number of portfolio weights to constrain.
total_weight – Target sum of weights. None disables the equality row.
long_only – When True append -I w <= 0 so weights remain non-negative.
bounds – Either a single (lower, upper) tuple applied to every asset, a sequence of per-asset tuples, or a mapping asset -> (lower, upper).
relative_bounds – Sequence of triples (i, j, bound) implementing w_i - w_j <= bound style constraints.
group_constraints – Mapping of group name to (indices, lower, upper) tuples. Each entry constrains the sum of weights in the group to lie between lower and upper.
additional_G_h – Extra inequality rows supplied as (row, rhs) pairs.
additional_A_b – Extra equality rows supplied as (row, rhs) pairs.
return_none_if_empty – When True return None instead of empty arrays.

Returns:

Tuple (G, h, A, b) suitable for CVXOPT/QP front-end functions. Each entry is None when no constraint of that type is required.

Parameters:

n_assets (int)
total_weight (int | float | None)
long_only (bool)
bounds (Tuple[int | float, int | float] | Sequence[Tuple[int | float, int | float]] | Dict[int, Tuple[int | float, int | float]] | None)
relative_bounds (Sequence[Tuple[int, int, int | float]] | None)
group_constraints (Dict[str, Tuple[Sequence[int], int | float, int | float]] | None)
additional_G_h (Sequence[Tuple[Sequence[int | float], int | float]] | None)
additional_A_b (Sequence[Tuple[Sequence[int | float], int | float]] | None)
return_none_if_empty (bool)

Return type:

Tuple[numpy.ndarray | None, numpy.ndarray | None, numpy.ndarray | None, numpy.ndarray | None]

Functions

pyvallocation.utils.constraints.build_G_h_A_b(n_assets, *, total_weight=1.0, long_only=True, bounds=None, relative_bounds=None, group_constraints=None, additional_G_h=None, additional_A_b=None, return_none_if_empty=True)[source]

Assemble inequality and equality constraints for portfolio optimisers.

The helper converts high-level constraint specifications (long-only, box bounds, pairwise relative bounds, and custom rows) into the G, h, A and b matrices expected by CVXOPT-based solvers.

Parameters:

n_assets – Number of portfolio weights to constrain.
total_weight – Target sum of weights. None disables the equality row.
long_only – When True append -I w <= 0 so weights remain non-negative.
bounds – Either a single (lower, upper) tuple applied to every asset, a sequence of per-asset tuples, or a mapping asset -> (lower, upper).
relative_bounds – Sequence of triples (i, j, bound) implementing w_i - w_j <= bound style constraints.
group_constraints – Mapping of group name to (indices, lower, upper) tuples. Each entry constrains the sum of weights in the group to lie between lower and upper.
additional_G_h – Extra inequality rows supplied as (row, rhs) pairs.
additional_A_b – Extra equality rows supplied as (row, rhs) pairs.
return_none_if_empty – When True return None instead of empty arrays.

Returns:

Tuple (G, h, A, b) suitable for CVXOPT/QP front-end functions. Each entry is None when no constraint of that type is required.

Parameters:

n_assets (int)
total_weight (int | float | None)
long_only (bool)
bounds (Tuple[int | float, int | float] | Sequence[Tuple[int | float, int | float]] | Dict[int, Tuple[int | float, int | float]] | None)
relative_bounds (Sequence[Tuple[int, int, int | float]] | None)
group_constraints (Dict[str, Tuple[Sequence[int], int | float, int | float]] | None)
additional_G_h (Sequence[Tuple[Sequence[int | float], int | float]] | None)
additional_A_b (Sequence[Tuple[Sequence[int | float], int | float]] | None)
return_none_if_empty (bool)

Return type:

Tuple[numpy.ndarray | None, numpy.ndarray | None, numpy.ndarray | None, numpy.ndarray | None]