Sensor Placement API Reference
Data
Data model for Sensor Placement use case.
SensorPlacementData
Bases: UcData
Data for the Sensor Placement use case.
Finds the optimal placement of sensors on a network graph to maximize coverage while respecting cost and count constraints.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
Literal['sensor_placement']
|
Identifier for this data type. |
adjacency_matrix |
AdjMatrix
|
An n x n weighted adjacency matrix of the network. |
node_names |
list[int] | list[str]
|
Identifiers for each node. Must be all ints or all strings. |
costs |
NumPyArray
|
Cost of placing a sensor at each node. |
n_sensors |
int
|
Number of sensors to place. |
plot(*, ax: Axes | None = None) -> Axes
Plot the network graph.
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 describing the data.
Returns:
| Type | Description |
|---|---|
str
|
String representation of the data. |
from_adjacency_matrix(adjacency_matrix: np.ndarray, node_names: list[int] | list[str], costs: list[float], n_sensors: int) -> SensorPlacementData
staticmethod
Create a SensorPlacementData instance from an adjacency matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adjacency_matrix
|
ndarray
|
Symmetric weighted adjacency matrix of the network. |
required |
node_names
|
list[int] | list[str]
|
Node identifiers. Length must match the matrix dimensions. |
required |
costs
|
list[float]
|
Cost of placing a sensor at each node. |
required |
n_sensors
|
int
|
Number of sensors to place. |
required |
Returns:
| Type | Description |
|---|---|
SensorPlacementData
|
The Sensor Placement data instance. |
from_graph(graph: nx.Graph, costs: list[float], n_sensors: int) -> SensorPlacementData
staticmethod
Create a SensorPlacementData instance from a NetworkX graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
graph
|
Graph
|
A NetworkX graph with optional edge weights. |
required |
costs
|
list[float]
|
Cost of placing a sensor at each node. |
required |
n_sensors
|
int
|
Number of sensors to place. |
required |
Returns:
| Type | Description |
|---|---|
SensorPlacementData
|
The Sensor Placement data instance. |
generate_random(n_nodes: int = 6, n_sensors: int = 2, seed: int | None = None) -> SensorPlacementData
staticmethod
Generate a random Sensor Placement instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_nodes
|
int
|
Number of nodes in the network, by default 6. |
6
|
n_sensors
|
int
|
Number of sensors to place, by default 2. |
2
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
Returns:
| Type | Description |
|---|---|
SensorPlacementData
|
A randomly generated data instance. |
Formulation
Formulation for Sensor Placement use case.
SensorPlacementFormulation
Bases: UcFormulation[SensorPlacementData, SensorPlacementSolution]
Constraint-based formulation for Sensor Placement.
Mathematical Formulation
Decision Variables:
x_i in {0,1}: 1 if a sensor is placed at node i
Objective:
maximize sum_{(i,j) edges} w_ij * (x[i] + x[j] - x[i] * x[j])
- sum_i costs[i] * x[i]
An edge is covered when at least one endpoint has a sensor
(x[i] OR x[j], linearized as x[i] + x[j] - x[i] * x[j]).
Constraints:
sum_i x[i] == n_sensors
to_string(data: SensorPlacementData) -> str
staticmethod
Return a string describing the formulation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
SensorPlacementData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
str
|
String representation of the formulation. |
formulate(data: SensorPlacementData) -> Model
staticmethod
Formulate the Sensor Placement problem.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
SensorPlacementData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
Model
|
A LunaModel ready to be solved. |
interpret(solution: Solution, data: SensorPlacementData) -> SensorPlacementSolution
staticmethod
Extract solution from quantum result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solution
|
Solution
|
The quantum solution. |
required |
data
|
SensorPlacementData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
SensorPlacementSolution
|
Structured solution with metrics. |
Solution
Solution model for Sensor Placement use case.
SensorPlacementSolution
Bases: UcSolution
Solution for the Sensor Placement use case.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
Literal['sensor_placement']
|
Identifier for this solution type. |
sensor_nodes |
list[int | str]
|
Nodes where sensors are placed. |
coverage_value |
float
|
Total coverage value from edge contributions. |
total_cost |
float
|
Total cost of placing sensors. |
is_valid |
bool
|
Whether exactly n_sensors sensors are placed. |
plot(data: SensorPlacementData | None = None, *, ax: Axes | None = None) -> Axes
Plot the sensor placement solution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
SensorPlacementData | None
|
Problem data for context. |
None
|
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 describing the solution.
Returns:
| Type | Description |
|---|---|
str
|
String representation of the solution. |
Instance
Instance model for SensorPlacement use case.
SensorPlacementInstance
Bases: UcInstance[SensorPlacementData, SensorPlacementFormulation, SensorPlacementSolution]
Instance combining data and formulation for SensorPlacement.
Collection
Collection of Sensor Placement instances.
SensorPlacementCollection
Bases: UcInstanceCollection[SensorPlacementInstance]
Collection of Sensor Placement instances.
from_random(min_size: int | None = None, max_size: int | None = None, num_instances: int = 1, *, sizes: Sequence[int] | None = None, n_sensors: int = 2, seed: int | None = None) -> SensorPlacementCollection
classmethod
Generate random Sensor Placement instances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_size
|
int | None
|
Minimum number of nodes. |
None
|
max_size
|
int | None
|
Maximum number of nodes. |
None
|
num_instances
|
int
|
Number of instances per size, by default 1. |
1
|
n_sensors
|
int
|
Number of sensors, by default 2. |
2
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
sizes
|
Sequence[int] | None
|
Explicit sizes to generate, e.g. |
None
|
Returns:
| Type | Description |
|---|---|
SensorPlacementCollection
|
Collection containing 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 |