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 Luna Model 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, 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:
| Name | Type | Description | Default |
|---|---|---|---|
min_rows
|
int
|
Minimum number of rows in the grid garden. |
required |
max_rows
|
int
|
Maximum number of rows in the grid garden. |
required |
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
|
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. |