Utilities

╔══════════════════════════════════════════════════════════╗ ║ utils « boundary handling & data preprocessing » ║ ╚══════════════════════════════════════════════════════════╝

class satyre.utils.HyperspaceSolver(vector=None, border=10000.0)[source]

Resolve boundary crossings in a square toroidal arena.

Given a displacement vector that may extend beyond the arena borders, the solver decomposes it into a sequence of sub-steps that wrap around the edges.

Parameters:

vector (ndarray[tuple[Any, ...], dtype[floating]]) – A (2, 2) array where vector[0] is the start position and vector[1] is the (possibly out-of-bounds) end position.
border (float) – Half-width of the square arena. The arena spans [-border, border] on both axes.

Example

>>> import numpy as np
>>> from satyre.utils import HyperspaceSolver
>>> vec = np.array([[-9000., -9000.], [-14000., -16000.]])
>>> solver = HyperspaceSolver(vector=vec, border=10000)
>>> sub_steps = solver.solve()
>>> sub_steps[-1]  # final in-bounds position
array([...])

solve()[source]

Decompose the displacement into wrapped sub-steps.

Return type:: ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]
Returns:: Array of shape (2*K, 2) where rows alternate between entry points and exit / final points for each sub-step. The last row is the agent’s final in-bounds position.

satyre.utils.build_transition_matrices(idx_path, velo_path)[source]

Build Markov transition matrices from raw text files.

Parameters:

idx_path (str | Path) – Path to a text file containing one PM index per line (the recorded sequence of prototypical movements).
velo_path (str | Path) – Path to a CSV-like text file where each line holds thrust, slip, yaw velocities for one PM.

Return type:

tuple[ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]], ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]], ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]]

Returns:

A tuple (cumsum_matrix, pm_index, velocity_array) where:

cumsum_matrix — cumulative transition-probability matrix of shape (N+1, N+1) (row 0 / col 0 are header indices).
pm_index — companion index matrix of same shape mapping columns back to PM identifiers.
velocity_array — (N+1, 3) array of [thrust, slip, yaw] velocities.

Example

>>> from satyre.utils import build_transition_matrices
>>> trans, idx, velos = build_transition_matrices(
...     'data/ORL_IDX.txt', 'data/ORL_C.txt'
... )

HyperspaceSolver

class satyre.utils.hyperspace_solver.HyperspaceSolver(vector=None, border=10000.0)[source]

Bases: object

Resolve boundary crossings in a square toroidal arena.

Given a displacement vector that may extend beyond the arena borders, the solver decomposes it into a sequence of sub-steps that wrap around the edges.

Parameters:

vector (ndarray[tuple[Any, ...], dtype[floating]]) – A (2, 2) array where vector[0] is the start position and vector[1] is the (possibly out-of-bounds) end position.
border (float) – Half-width of the square arena. The arena spans [-border, border] on both axes.

Example

>>> import numpy as np
>>> from satyre.utils import HyperspaceSolver
>>> vec = np.array([[-9000., -9000.], [-14000., -16000.]])
>>> solver = HyperspaceSolver(vector=vec, border=10000)
>>> sub_steps = solver.solve()
>>> sub_steps[-1]  # final in-bounds position
array([...])

solve()[source]

Decompose the displacement into wrapped sub-steps.

Return type:: ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]
Returns:: Array of shape (2*K, 2) where rows alternate between entry points and exit / final points for each sub-step. The last row is the agent’s final in-bounds position.

Preprocessing

╔══════════════════════════════════════════════════════════╗ ║ preprocessing « build Markov transition matrices » ║ ╚══════════════════════════════════════════════════════════╝

Converts raw experimental data (prototypical-movement index sequences and velocity tables) into the cumulative transition- probability matrices consumed by MarkovWalker.

satyre.utils.preprocessing.build_transition_matrices(idx_path, velo_path)[source]

Build Markov transition matrices from raw text files.

Parameters:

idx_path (str | Path) – Path to a text file containing one PM index per line (the recorded sequence of prototypical movements).
velo_path (str | Path) – Path to a CSV-like text file where each line holds thrust, slip, yaw velocities for one PM.

Return type:

tuple[ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]], ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]], ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]]

Returns:

A tuple (cumsum_matrix, pm_index, velocity_array) where:

cumsum_matrix — cumulative transition-probability matrix of shape (N+1, N+1) (row 0 / col 0 are header indices).
pm_index — companion index matrix of same shape mapping columns back to PM identifiers.
velocity_array — (N+1, 3) array of [thrust, slip, yaw] velocities.

Example

>>> from satyre.utils import build_transition_matrices
>>> trans, idx, velos = build_transition_matrices(
...     'data/ORL_IDX.txt', 'data/ORL_C.txt'
... )

satyre.utils.preprocessing.main()[source]

CLI entry point for satyre-preprocess.

Usage:

satyre-preprocess --idx data/ORL_IDX.txt \
                  --velo data/ORL_C.txt   \
                  --out  data/preprocessed

Return type:: None