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 Luna Model 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, max_rows: int, n_cols: int = 3, n_species: int = 3, num_instances: int = 1, *, seed: int | None = None) -> GardenOptimizationCollection classmethod

Generate random garden optimization instances with varying sizes.

Parameters:

  • min_rows (int) –

    Minimum number of rows in the grid garden.

  • max_rows (int) –

    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.

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: