Skip to content

Method

sgptools.methods.Method

Base class for informative sensing / path-planning optimization methods.

All methods optimize a set of sensing locations or waypoints, typically under a task-specific objective defined over a Gaussian process model (e.g., mutual information, ELBO).

Attributes:

Name Type Description
num_sensing int

Number of sensing locations (or waypoints) to optimize per robot.
num_dim int

Dimensionality of each sensing location (e.g., 2 for (x, y), 3 for (x, y, θ)).
num_robots int

Number of robots / agents whose paths or sensing locations are being optimized.
X_candidates ndarray | None

Optional discrete set of candidate sensing locations with shape (c, num_dim). If provided, continuous solutions may be snapped to the closest candidates via cont2disc.
Source code in sgptools/methods.py 
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
class Method:
    """Base class for informative sensing / path-planning optimization methods.

    All methods optimize a set of sensing locations or waypoints,
    typically under a task-specific objective defined over a Gaussian process
    model (e.g., mutual information, ELBO).

    Attributes:
        num_sensing (int):
            Number of sensing locations (or waypoints) to optimize
            per robot.
        num_dim (int):
            Dimensionality of each sensing location (e.g., 2 for (x, y),
            3 for (x, y, θ)).
        num_robots (int):
            Number of robots / agents whose paths or sensing locations
            are being optimized.
        X_candidates (np.ndarray | None):
            Optional discrete set of candidate sensing locations
            with shape `(c, num_dim)`. If provided, continuous solutions may be
            snapped to the closest candidates via `cont2disc`.
    """

    def __init__(self,
                 num_sensing: int,
                 X_objective: np.ndarray,
                 kernel: gpflow.kernels.Kernel,
                 noise_variance: float,
                 transform: Optional[Transform] = None,
                 num_robots: int = 1,
                 X_candidates: Optional[np.ndarray] = None,
                 num_dim: Optional[int] = None,
                 **kwargs: Any):
        """Base initializer for an optimization method.

        Args:
            num_sensing (int):
                Number of sensing locations (inducing points / waypoints) to be
                optimized per robot.
            X_objective (np.ndarray):
                Array of shape `(n, d)` containing the inputs used to define the
                objective (e.g., training inputs or a spatial grid). The last
                dimension `d` is used as the default `num_dim` if `num_dim` is not
                provided explicitly.
            kernel (gpflow.kernels.Kernel):
                GPflow kernel used by the objective. Stored only indirectly through
                subclasses (via their objective models).
            noise_variance (float):
                Observation noise variance used in the objective.
            transform (Transform | None):
                Optional `Transform` object that maps inducing points to an
                expanded representation (e.g., IPP path expansion, sensor FoV).
                Also used for constraint evaluation. Not stored here, but passed
                through to subclasses as needed.
            num_robots (int):
                Number of robots / agents. The total number of optimized points
                is `num_sensing * num_robots`. Defaults to 1.
            X_candidates (np.ndarray | None):
                Optional array of shape `(c, d)` representing a discrete set of
                feasible sensing locations. When provided, many methods map their
                continuous solution to this candidate set using `cont2disc`.
            num_dim (int | None):
                Dimensionality of each sensing location. If `None`, defaults to
                `X_objective.shape[-1]`.
            **kwargs (Any):
                Additional keyword arguments are accepted for forward compatibility,
                but ignored by the base class.
        """
        self.num_sensing = num_sensing
        self.num_robots = num_robots
        self.X_candidates = X_candidates
        if num_dim is None:
            self.num_dim = X_objective.shape[-1]
        else:
            self.num_dim = num_dim

    def optimize(self) -> np.ndarray:
        """Run the optimization procedure and return the optimized sensing
        locations / waypoints.

        Returns:
            np.ndarray:
                Array with shape `(num_robots, num_sensing, num_dim)` containing
                the optimized sensing locations.

        Raises:
            NotImplementedError:
                Must be implemented in subclasses.
        """
        raise NotImplementedError

    def update(self, kernel: gpflow.kernels.Kernel,
               noise_variance: float) -> None:
        """Update the kernel and noise-variance hyperparameters used by the
        underlying objective or SGP model.

        Args:
            kernel (gpflow.kernels.Kernel):
                New GPflow kernel instance.
            noise_variance (float):
                New observation noise variance.

        Raises:
            NotImplementedError:
                Must be implemented in subclasses.
        """
        raise NotImplementedError

    def get_hyperparameters(self) -> Tuple[gpflow.kernels.Kernel, float]:
        """Return the current kernel and noise-variance hyperparameters used by
        the underlying objective or SGP model.

        Returns:
            Tuple[gpflow.kernels.Kernel, float]:
                A tuple `(kernel, noise_variance)` containing copies of the current
                hyperparameters.

        Raises:
            NotImplementedError:
                Must be implemented in subclasses.
        """
        raise NotImplementedError

__init__(num_sensing, X_objective, kernel, noise_variance, transform=None, num_robots=1, X_candidates=None, num_dim=None, **kwargs)

Base initializer for an optimization method.

Parameters:

Name Type Description Default
num_sensing int

Number of sensing locations (inducing points / waypoints) to be optimized per robot.

 required
X_objective ndarray

Array of shape (n, d) containing the inputs used to define the objective (e.g., training inputs or a spatial grid). The last dimension d is used as the default num_dim if num_dim is not provided explicitly.

 required
kernel Kernel

GPflow kernel used by the objective. Stored only indirectly through subclasses (via their objective models).

 required
noise_variance float

Observation noise variance used in the objective.

 required
transform Transform | None

Optional Transform object that maps inducing points to an expanded representation (e.g., IPP path expansion, sensor FoV). Also used for constraint evaluation. Not stored here, but passed through to subclasses as needed.

 None
num_robots int

Number of robots / agents. The total number of optimized points is num_sensing * num_robots. Defaults to 1.

 1
X_candidates ndarray | None

Optional array of shape (c, d) representing a discrete set of feasible sensing locations. When provided, many methods map their continuous solution to this candidate set using cont2disc.

 None
num_dim int | None

Dimensionality of each sensing location. If None, defaults to X_objective.shape[-1].

 None
**kwargs Any

Additional keyword arguments are accepted for forward compatibility, but ignored by the base class.

 {}
Source code in sgptools/methods.py 
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def __init__(self,
             num_sensing: int,
             X_objective: np.ndarray,
             kernel: gpflow.kernels.Kernel,
             noise_variance: float,
             transform: Optional[Transform] = None,
             num_robots: int = 1,
             X_candidates: Optional[np.ndarray] = None,
             num_dim: Optional[int] = None,
             **kwargs: Any):
    """Base initializer for an optimization method.

    Args:
        num_sensing (int):
            Number of sensing locations (inducing points / waypoints) to be
            optimized per robot.
        X_objective (np.ndarray):
            Array of shape `(n, d)` containing the inputs used to define the
            objective (e.g., training inputs or a spatial grid). The last
            dimension `d` is used as the default `num_dim` if `num_dim` is not
            provided explicitly.
        kernel (gpflow.kernels.Kernel):
            GPflow kernel used by the objective. Stored only indirectly through
            subclasses (via their objective models).
        noise_variance (float):
            Observation noise variance used in the objective.
        transform (Transform | None):
            Optional `Transform` object that maps inducing points to an
            expanded representation (e.g., IPP path expansion, sensor FoV).
            Also used for constraint evaluation. Not stored here, but passed
            through to subclasses as needed.
        num_robots (int):
            Number of robots / agents. The total number of optimized points
            is `num_sensing * num_robots`. Defaults to 1.
        X_candidates (np.ndarray | None):
            Optional array of shape `(c, d)` representing a discrete set of
            feasible sensing locations. When provided, many methods map their
            continuous solution to this candidate set using `cont2disc`.
        num_dim (int | None):
            Dimensionality of each sensing location. If `None`, defaults to
            `X_objective.shape[-1]`.
        **kwargs (Any):
            Additional keyword arguments are accepted for forward compatibility,
            but ignored by the base class.
    """
    self.num_sensing = num_sensing
    self.num_robots = num_robots
    self.X_candidates = X_candidates
    if num_dim is None:
        self.num_dim = X_objective.shape[-1]
    else:
        self.num_dim = num_dim

get_hyperparameters()

Return the current kernel and noise-variance hyperparameters used by the underlying objective or SGP model.

Returns:

Type Description
Tuple[Kernel, float]

Tuple[gpflow.kernels.Kernel, float]: A tuple (kernel, noise_variance) containing copies of the current hyperparameters.

Raises:

Type Description
NotImplementedError

Must be implemented in subclasses.
Source code in sgptools/methods.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def get_hyperparameters(self) -> Tuple[gpflow.kernels.Kernel, float]:
    """Return the current kernel and noise-variance hyperparameters used by
    the underlying objective or SGP model.

    Returns:
        Tuple[gpflow.kernels.Kernel, float]:
            A tuple `(kernel, noise_variance)` containing copies of the current
            hyperparameters.

    Raises:
        NotImplementedError:
            Must be implemented in subclasses.
    """
    raise NotImplementedError

optimize()

Run the optimization procedure and return the optimized sensing locations / waypoints.

Returns:

Type Description
ndarray

np.ndarray: Array with shape (num_robots, num_sensing, num_dim) containing the optimized sensing locations.

Raises:

Type Description
NotImplementedError

Must be implemented in subclasses.
Source code in sgptools/methods.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def optimize(self) -> np.ndarray:
    """Run the optimization procedure and return the optimized sensing
    locations / waypoints.

    Returns:
        np.ndarray:
            Array with shape `(num_robots, num_sensing, num_dim)` containing
            the optimized sensing locations.

    Raises:
        NotImplementedError:
            Must be implemented in subclasses.
    """
    raise NotImplementedError

update(kernel, noise_variance)

Update the kernel and noise-variance hyperparameters used by the underlying objective or SGP model.

Parameters:

Name Type Description Default
kernel Kernel

New GPflow kernel instance.

 required
noise_variance float

New observation noise variance.

 required

Raises:

Type Description
NotImplementedError

Must be implemented in subclasses.
Source code in sgptools/methods.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
def update(self, kernel: gpflow.kernels.Kernel,
           noise_variance: float) -> None:
    """Update the kernel and noise-variance hyperparameters used by the
    underlying objective or SGP model.

    Args:
        kernel (gpflow.kernels.Kernel):
            New GPflow kernel instance.
        noise_variance (float):
            New observation noise variance.

    Raises:
        NotImplementedError:
            Must be implemented in subclasses.
    """
    raise NotImplementedError