Skip to content

CostSegment 

CostSegment(alssm, segment, beta=1.0, label='n/a')

Bases: BaseCost, BaseCost1d


              flowchart TD
              lmlib.statespace.cost.CostSegment[CostSegment]
              lmlib.statespace.cost.BaseCost[BaseCost]
              lmlib.statespace.cost.BaseCost1d[BaseCost1d]

                              lmlib.statespace.cost.BaseCost --> lmlib.statespace.cost.CostSegment
                
                lmlib.statespace.cost.BaseCost1d --> lmlib.statespace.cost.CostSegment
                


              click lmlib.statespace.cost.CostSegment href "" "lmlib.statespace.cost.CostSegment"
              click lmlib.statespace.cost.BaseCost href "" "lmlib.statespace.cost.BaseCost"
              click lmlib.statespace.cost.BaseCost1d href "" "lmlib.statespace.cost.BaseCost1d"

Quadratic cost function defined by an ALSSM and a Segment.

A CostSegment is an implementation of [Wildhaber2019] PDF (Cost Segment)

==================
Class: CostSegment (= 1 ALSSM + 1 Segment)
==================

  window weight
      ^
    2_|                   ___     exponentially rising window of a segment
    1_|              ____/     <- normalized to 1 at index delta; to
    0_|    _________/             weight the cost function

               segment
           +----------------+
  alssm    |                |
           +----------------+

           |--|-------|-----|----> k (time, relativ to the segment reference index 0)
           a  0     delta   b

  a, b : segment interval boundaries (integers or ±∞), a < b

A cost segment is the quadratic cost function

\[ J_a^b(k,x,\theta) = \sum_{i=k+a}^{k+b} \alpha_{k+\delta}(i)v_i(y_i - cA^{i-k}x)^2 \]

over a fixed interval \(\{a, \dots, b\}\) with \(a \in \mathbb{Z} \cup \{ - \infty \}\), \(b \in \mathbb{Z} \cup \{ + \infty\}\), and \(a < b\), and with initial state vector \(x \in \mathbb{R}^{N \times 1}\). For more details, see Section 4.2.6 and Chapter 9 in [Wildhaber2019] .

Parameters:

  • alssm (ModelBase) –

    ALSSM defining the signal model.

  • segment (Segment) –

    Segment defining the window shape and recursion direction.

  • beta (float, default: 1.0 ) –

    Non-negative scaling factor on this cost term. Default: 1.0.

  • label (str, default: 'n/a' ) –

    Label of the CostSegment. Default: 'n/a'.

Examples:

Set up a cost segment with finite boundaries and a line ALSSM.

>>> import lmlib as lm
>>> alssm_line = lm.AlssmPoly(poly_degree=1, label="slope with offset")
>>> segment_left = lm.Segment(a=-30, b=0, direction=lm.FORWARD, g=20, label="finite left")
>>> cost = lm.CostSegment(alssm_line, segment_left, label="left line")
>>> print(cost)
CostSegment(label: left line)
  └- AlssmPoly(A=[[1 1],[0 1]], C=[1 0], label=slope with offset),
  └- Segment(a=-30, b=0, direction=fw, g=20, delta=0, label=finite left)

Methods:

Attributes:

  • label –

    str : Label of the CostSegment.

  • alssm –

    ModelBase : The ALSSM signal model attached to this cost segment.

  • segment –

    Segment : The window/segment attached to this cost segment.

  • beta –

    float : Non-negative scaling factor \(\beta\) on this cost segment.

Source code in lmlib/statespace/cost.py 
216
217
218
219
220
221
def __init__(self, alssm, segment, beta=1.0, label='n/a'):
    self.alssm = alssm
    self.segment = segment
    self.beta = beta
    self.label = label
    r"""str : Label of the CostSegment."""

Methods

get_alssm_order 

get_alssm_order() -> int

Return the state-space order N of the attached ALSSM.

Source code in lmlib/statespace/cost.py 
263
264
265
def get_alssm_order(self) -> int:
    """Return the state-space order N of the attached ALSSM."""
    return self.alssm.N

get_number_of_dimensions 

get_number_of_dimensions()

Return 1 — a CostSegment always represents a single dimension.

Source code in lmlib/statespace/cost.py 
267
268
269
def get_number_of_dimensions(self):
    """Return 1 — a CostSegment always represents a single dimension."""
    return 1

get_alssm_output_dimension 

get_alssm_output_dimension() -> int

Return the output dimension Q of the attached ALSSM.

Source code in lmlib/statespace/cost.py 
271
272
273
def get_alssm_output_dimension(self) -> int:
    """Return the output dimension Q of the attached ALSSM."""
    return self.alssm.get_alssm_output_dimension()

get_steady_state_W 

get_steady_state_W(dim_order=None, method='schur')

Compute the steady-state Gram matrix W for this cost segment.

Parameters:

  • dim_order (ignored, default: None ) –

    Accepted for interface compatibility; unused for 1-D costs.

  • method (str, default: 'schur' ) –

    Computation method: 'schur' (default), 'closed_form', or 'limited_sum'.

Returns:

  • W ( ndarray of shape (N, N) ) –

    Steady-state Gram matrix.

Source code in lmlib/statespace/cost.py 
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
def get_steady_state_W(self, dim_order=None, method='schur'):
    """
    Compute the steady-state Gram matrix W for this cost segment.

    Parameters
    ----------
    dim_order : ignored
        Accepted for interface compatibility; unused for 1-D costs.
    method : str, optional
        Computation method: ``'schur'`` (default), ``'closed_form'``,
        or ``'limited_sum'``.

    Returns
    -------
    W : ndarray of shape (N, N)
        Steady-state Gram matrix.
    """
    A, C = self.alssm.A, self.alssm.C
    gamma = self.segment.gamma
    a, b, delta = self.segment.a, self.segment.b, self.segment.delta

    if method == 'schur':
        basis = getattr(self.alssm, 'steady_state_basis', None)
        return covariance_matrix_schur(A, C, gamma, a, b, delta, basis=basis)
    elif method == 'closed_form':
        return covariance_matrix_closed_form(A, C, gamma, a, b, delta)
    elif method == 'limited_sum':
        return covariance_matrix_limited_sum(A, C, gamma, a, b, delta)
    else:
        raise NotImplementedError(f'unknown method {method}')

get_state_var_indices 

get_state_var_indices(label)

Return the state indices corresponding to a named state variable.

Parameters:

  • label (str) –

    State variable label as registered in the ALSSM.

Returns:

  • indices ( list of int ) –

    Indices into the state vector for the labelled variable.

Source code in lmlib/statespace/cost.py 
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
def get_state_var_indices(self, label):
    """
    Return the state indices corresponding to a named state variable.

    Parameters
    ----------
    label : str
        State variable label as registered in the ALSSM.

    Returns
    -------
    indices : list of int
        Indices into the state vector for the labelled variable.
    """
    return self.alssm.get_state_var_indices(label)

eval_alssm_output 

eval_alssm_output(xs, alssm_weights=None)

Evaluate the ALSSM output for a set of state vectors.

Parameters:

  • xs (array_like of shape (..., N)) –

    State vectors; the last dimension must match the model order N.

  • alssm_weights (None, scalar, or array_like, default: None ) –

    Output weights forwarded to AlssmSum. Default: None.

Returns:

  • out ( ndarray ) –

    ALSSM output sequences for each state vector in xs.

Source code in lmlib/statespace/cost.py 
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
def eval_alssm_output(self, xs, alssm_weights=None):
    r"""
    Evaluate the ALSSM output for a set of state vectors.

    Parameters
    ----------
    xs : array_like of shape (..., N)
        State vectors; the last dimension must match the model order N.
    alssm_weights : None, scalar, or array_like, optional
        Output weights forwarded to [`AlssmSum`][lmlib.statespace.model.AlssmSum]. Default: None.

    Returns
    -------
    out : ndarray
        ALSSM output sequences for each state vector in ``xs``.
    """
    return AlssmSum([self.alssm], alssm_weights).eval_output(xs)

get_alssms 

get_alssms()

Return a list containing the single ALSSM of this cost segment.

Source code in lmlib/statespace/cost.py 
340
341
342
def get_alssms(self):
    """Return a list containing the single ALSSM of this cost segment."""
    return [self.alssm]