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 | Type | Description |
|---|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Axes | None
|
Matplotlib axes to draw on. Creates a new figure if |
None
|
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
graph
|
Graph
|
A NetworkX graph whose nodes are (row, col) tuples. |
required |
count
|
ndarray
|
Number of plants needed per species. |
required |
compatibility
|
ndarray
|
Compatibility matrix between species. |
required |
Returns:
| Type | Description |
|---|---|
GardenOptimizationData
|
The garden optimization data instance. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
n_rows
|
int
|
Number of rows in the grid garden. |
3
|
n_cols
|
int
|
Number of columns in the grid garden. |
3
|
n_species
|
int
|
Number of plant species. |
3
|
seed
|
int | None
|
Random seed for reproducibility. |
None
|
Returns:
| Type | Description |
|---|---|
GardenOptimizationData
|
A randomly generated data instance. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
GardenOptimizationData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Formatted description of the formulation. |
formulate(data: GardenOptimizationData) -> Model
staticmethod
Formulate the garden optimization problem.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
GardenOptimizationData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
Model
|
A LunaModel ready to be solved. |
interpret(solution: Solution, data: GardenOptimizationData) -> GardenOptimizationSolution
staticmethod
Extract the garden optimization solution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solution
|
Solution
|
The solver solution. |
required |
data
|
GardenOptimizationData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
GardenOptimizationSolution
|
Structured solution with plant assignments. |
Solution
Solution model for Garden Optimization use case.
GardenOptimizationSolution
Bases: UcSolution
Solution for the Garden Optimization use case.
Attributes:
| Name | Type | Description |
|---|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
GardenOptimizationData | None
|
Problem data for reconstructing the graph. Required. |
None
|
ax
|
Axes | None
|
Matplotlib axes to draw on. |
None
|
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
min_rows
|
int | None
|
Minimum number of rows in the grid garden. |
None
|
max_rows
|
int | None
|
Maximum number of rows in the grid garden. |
None
|
n_cols
|
int
|
Number of columns in the grid garden. |
3
|
n_species
|
int
|
Number of plant species. |
3
|
num_instances
|
int
|
Instances per size. |
1
|
seed
|
int | None
|
Random seed. |
None
|
sizes
|
Sequence[int] | None
|
Explicit sizes to generate, e.g. |
None
|
Returns:
| Type | Description |
|---|---|
GardenOptimizationCollection
|
Collection of generated instances. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
grid_sizes
|
list[tuple[int, int]]
|
List of (n_rows, n_cols) tuples specifying garden sizes. |
required |
n_species
|
int
|
Number of plant species. |
3
|
num_instances
|
int
|
Instances per grid size. |
1
|
seed
|
int | None
|
Random seed. |
None
|
Returns:
| Type | Description |
|---|---|
GardenOptimizationCollection
|
Collection of generated instances. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
max_runtime
|
float
|
SCIP time limit per instance in seconds. Must be positive. Defaults to 3600 seconds. |
3600
|
quiet
|
bool
|
Suppress the SCIP solver output. |
True
|
Returns:
| Type | Description |
|---|---|
list[bool]
|
Feasibility mask over the instances as they were before filtering,
in that order: |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |