pylinkage.collections package

Submodules

pylinkage.collections.agent module

Agent class for optimization results.

pylinkage.collections.mutable_agent module

MutableAgent class for optimization results.

Module contents

Package for collection objects.

class pylinkage.collections.Agent(score: float, dimensions: Any = None, initial_positions: Sequence[tuple[float | None, float | None]]=(), *, init_positions: Any = <object object>)

Bases: _AgentBase

A class that uniformizes a linkage optimization.

It is roughly a namedtuple with preassigned fields.

The initial_positions field can also be accessed as init_positions for backwards compatibility.

property init_positions: Sequence[tuple[float | None, float | None]]

Backwards-compatible alias for initial_positions.

class pylinkage.collections.MutableAgent(score: float | None = None, dimensions: Sequence[float] | None = None, initial_positions: Sequence[tuple[float | None, float | None]] | None = None, init_position: Sequence[tuple[float | None, float | None]] | None = None)

Bases: object

A custom class that is mutable, subscriptable, and supports index assignment.

You should only use it as a dictionary of 3 elements. No backward compatibility guaranty on other use cases.

dimensions: Sequence[float] | None

property init_positions: Sequence[tuple[float | None, float | None]] | None

Backwards-compatible alias for initial_positions.

initial_positions: Sequence[tuple[float | None, float | None]] | None

score: float | None

class pylinkage.collections.ParetoFront(solutions: list[~pylinkage.optimization.collections.pareto.ParetoSolution], objective_names: tuple[str, ...] = <factory>)

Bases: object

Collection of non-dominated solutions from multi-objective optimization.

Attributes:

solutions: List of Pareto-optimal solutions. objective_names: Names for each objective (for plotting).

best_compromise(weights: Sequence[float] | None = None) → ParetoSolution

Select the best compromise solution.

Uses weighted sum of normalized objectives to find a balanced solution.

Args:

weights: Weight for each objective. If None, uses equal weights.

Returns:

The solution with the lowest weighted sum.

Raises:

ValueError: If the front is empty.

filter(max_solutions: int) → ParetoFront

Filter to a subset of well-distributed solutions.

Uses crowding distance to select diverse solutions.

Args:

max_solutions: Maximum number of solutions to keep.

Returns:

New ParetoFront with at most max_solutions solutions.

hypervolume(reference_point: Sequence[float]) → float

Compute the hypervolume indicator.

The hypervolume is the volume of the objective space dominated by the Pareto front and bounded by a reference point. Higher is better.

Args:

reference_point: Upper bound for each objective. Should be

worse than any solution in the front.

Returns:

The hypervolume indicator value.

Raises:

ImportError: If pymoo is not installed.

property n_objectives: int

Return the number of objectives.

objective_names: tuple[str, ...]

plot(ax: Axes | None = None, objective_indices: tuple[int, int] | tuple[int, int, int] = (0, 1), **kwargs: Any) → Figure

Plot the Pareto front.

For 2 objectives: Creates a 2D scatter plot. For 3 objectives: Creates a 3D scatter plot.

Args:

ax: Matplotlib axes to plot on. If None, creates new figure. objective_indices: Which objectives to plot (indices). **kwargs: Additional arguments passed to scatter().

Returns:

The matplotlib Figure containing the plot.

Raises:

ValueError: If the front is empty or indices are invalid.

scores_array() → ndarray[tuple[Any, ...], dtype[floating[Any]]]

Return all scores as a 2D numpy array.

Returns:

Array of shape (n_solutions, n_objectives).

solutions: list[ParetoSolution]

class pylinkage.collections.ParetoSolution(scores: tuple[float, ...], dimensions: NDArray[np.floating[Any]], initial_positions: JointPositions = (), *, init_positions: JointPositions | None = None)

Bases: object

A single solution on the Pareto front.

Attributes:

scores: Objective values, one per objective (all minimized). dimensions: Constraint values that produced this solution. initial_positions: Initial joint positions used during optimization.

dimensions: NDArray[np.floating[Any]]

dominates(other: ParetoSolution) → bool

Check if this solution dominates another.

A solution dominates another if it is at least as good in all objectives and strictly better in at least one.

Args:

other: Another Pareto solution to compare against.

Returns:

True if this solution dominates the other.

property init_positions: JointPositions

Backwards-compatible alias for initial_positions.

initial_positions: JointPositions = ()

scores: tuple[float, ...]