Skip to content

Garden Optimization API Reference

Data

Data model for Garden Optimization use case.

GardenOptimizationData

Bases: UcData

Data for the Garden Optimization use case.

The garden optimization problem places plants of different species into pots arranged as a graph. The goal is to minimize antagonistic adjacencies and maximize friendly ones, subject to count constraints.

Attributes:

  • name (Literal['garden_optimization']) –

    Identifier for this data type.

  • adjacency_matrix (BinAdjMatrix) –

    Symmetric binary adjacency matrix of the garden graph (pots as nodes).

  • pot_names (list[tuple[int, int]]) –

    Pot coordinates (node identifiers).

  • count (NumPyArray) –

    Number of plants needed for each species (1D int array).

  • compatibility (SymMatrix) –

    Compatibility matrix between species: -1=friendly, 0=neutral, +1=antagonistic (2D int array).

plot(*, ax: Axes | None = None) -> Axes

Plot the garden graph instance.

Parameters:

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on. Creates a new figure if None.

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string representation of the data.

from_graph(graph: nx.Graph, count: np.ndarray, compatibility: np.ndarray) -> GardenOptimizationData staticmethod

Create data from a NetworkX graph.

Parameters:

  • graph (Graph) –

    A NetworkX graph whose nodes are (row, col) tuples.

  • count (ndarray) –

    Number of plants needed per species.

  • compatibility (ndarray) –

    Compatibility matrix between species.

Returns:

generate_random(n_rows: int = 3, n_cols: int = 3, n_species: int = 3, seed: int | None = None) -> GardenOptimizationData staticmethod

Generate a random garden optimization instance.

Parameters:

  • n_rows (int, default: 3 ) –

    Number of rows in the grid garden.

  • n_cols (int, default: 3 ) –

    Number of columns in the grid garden.

  • n_species (int, default: 3 ) –

    Number of plant species.

  • seed (int | None, default: None ) –

    Random seed for reproducibility.

Returns:

Formulation

Formulation for Garden Optimization use case.

GardenOptimizationFormulation

Bases: UcFormulation[GardenOptimizationData, GardenOptimizationSolution]

Constraint-based formulation for Garden Optimization.

Mathematical Formulation 
Symbols:
    P — number of pots
    S — number of plant species
    E — set of edges in the garden graph
    count[s] — required number of plants for species s
    compatibility[s1,s2] — relationship between species (-1=friendly, 0=neutral, +1=antagonistic)

Decision Variables:
    x[p,s] in {0,1} — 1 if a plant of species s is placed in pot p
        for p = 0, ..., P-1 and s = 0, ..., S-1

Objective:
    ``Minimize sum_{(p1,p2) in E} sum_{s1,s2} compatibility[s1][s2] * x[p1,s1] * x[p2,s2]``

Constraints:
    - Each pot gets exactly one plant: sum_s x[p,s] == 1 for each pot p
    - Species count is met: sum_p x[p,s] == count[s] for each species s

to_string(data: GardenOptimizationData) -> str staticmethod

Format the formulation as a string.

Parameters:

Returns:

  • str –

    Formatted description of the formulation.

formulate(data: GardenOptimizationData) -> Model staticmethod

Formulate the garden optimization problem.

Parameters:

Returns:

  • Model –

    A LunaModel ready to be solved.

interpret(solution: Solution, data: GardenOptimizationData) -> GardenOptimizationSolution staticmethod

Extract the garden optimization solution.

Parameters:

Returns:

Solution

Solution model for Garden Optimization use case.

GardenOptimizationSolution

Bases: UcSolution

Solution for the Garden Optimization use case.

Attributes:

  • name (Literal['garden_optimization']) –

    Identifier for this solution type.

  • plant_assignment (dict[str, int]) –

    Mapping from pot coordinate (as string key) to species index.

  • n_friendly_pairs (int) –

    Number of adjacent pot pairs with friendly relationship.

  • n_antagonistic_pairs (int) –

    Number of adjacent pot pairs with antagonistic relationship.

  • is_valid (bool) –

    Whether all plants are placed and all pots filled.

plot(data: GardenOptimizationData | None = None, *, ax: Axes | None = None) -> Axes

Plot the garden optimization solution.

Parameters:

  • data (GardenOptimizationData | None, default: None ) –

    Problem data for reconstructing the graph. Required.

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on.

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string representation of the solution.

Instance

Instance model for GardenOptimization use case.

GardenOptimizationInstance

Bases: UcInstance[GardenOptimizationData, GardenOptimizationFormulation, GardenOptimizationSolution]

Instance combining data and formulation for GardenOptimization.

Collection

Collection of Garden Optimization instances.

GardenOptimizationCollection

Bases: UcInstanceCollection[GardenOptimizationInstance]

Collection of Garden Optimization instances.

from_random(min_rows: int | None = None, max_rows: int | None = None, n_cols: int = 3, n_species: int = 3, num_instances: int = 1, *, sizes: Sequence[int] | None = None, seed: int | None = None) -> GardenOptimizationCollection classmethod

Generate random garden optimization instances with varying sizes.

Parameters:

  • min_rows (int | None, default: None ) –

    Minimum number of rows in the grid garden.

  • max_rows (int | None, default: None ) –

    Maximum number of rows in the grid garden.

  • n_cols (int, default: 3 ) –

    Number of columns in the grid garden.

  • n_species (int, default: 3 ) –

    Number of plant species.

  • num_instances (int, default: 1 ) –

    Instances per size.

  • seed (int | None, default: None ) –

    Random seed.

  • sizes (Sequence[int] | None, default: None ) –

    Explicit sizes to generate, e.g. [10, 50, 100], instead of a range. Mutually exclusive with min_rows/max_rows, by default None.

Returns:

from_grid(grid_sizes: list[tuple[int, int]], n_species: int = 3, num_instances: int = 1, *, seed: int | None = None) -> GardenOptimizationCollection classmethod

Generate garden optimization instances for specific grid sizes.

Parameters:

  • grid_sizes (list[tuple[int, int]]) –

    List of (n_rows, n_cols) tuples specifying garden sizes.

  • n_species (int, default: 3 ) –

    Number of plant species.

  • num_instances (int, default: 1 ) –

    Instances per grid size.

  • seed (int | None, default: None ) –

    Random seed.

Returns:

filter_infeasible(max_runtime: float = 3600, *, quiet: bool = True) -> list[bool]

Drop the instances of this collection that have no feasible solution.

Every instance is formulated and handed to SCIP, which stops as soon as it finds the first feasible solution. An instance is removed from the collection when SCIP proves the model infeasible, when no solution turns up within max_runtime, or when formulating it fails altogether. This keeps randomly generated instances from breaking a downstream pipeline.

Parameters:

  • max_runtime (float, default: 3600 ) –

    SCIP time limit per instance in seconds. Must be positive. Defaults to 3600 seconds.

  • quiet (bool, default: True ) –

    Suppress the SCIP solver output.

Returns:

  • list[bool] –

    Feasibility mask over the instances as they were before filtering, in that order: True where the instance was kept, False where it was removed.

Raises: