qilisdk.ml.datasets.dataset

Attributes

FloatArray
State

Classes

DatasetSample	A generated batch of samples produced by a Dataset.
Dataset	Abstract base class for ML datasets

Functions

rk4_step(→ State)	Advance a state by one fixed-step classic Runge--Kutta (RK4) step.
build_prediction_sample(→ DatasetSample)	Turn a time series into a prediction sample.

Module Contents

type FloatArray = 'NDArray[np.float32]'

State

rk4_step(state: State, dt: float, deriv: collections.abc.Callable[[State], State]) → State

Advance a state by one fixed-step classic Runge–Kutta (RK4) step.

Works for both scalar (float) and vector (FloatArray) states, since only NumPy-broadcastable arithmetic is used. For systems whose derivative depends on more than the current state (e.g. a delayed value), close the extra arguments into deriv so they stay fixed across the four stages.

Parameters:

• state (State) – Current state y_i.

• dt (float) – Integration step.

• deriv (Callable[[State], State]) – Function returning dy/dt for a given state.

Returns:

The state advanced by one step, y_{i+1}.

Return type:

State

class DatasetSample

A generated batch of samples produced by a Dataset. A sample is an (inputs, targets) pair.

inputs: FloatArray

targets: FloatArray

build_prediction_sample(series: FloatArray, horizon: int) → DatasetSample

Turn a time series into a prediction sample.

Given a series of length npoints + horizon, the inputs are the first npoints steps and the targets are the latter horizon steps.

Parameters:

• series (FloatArray) – The raw series

• horizon (int) – Number of steps ahead to predict. Must be positive.

Returns:

The aligned (inputs, targets) pair

Return type:

DatasetSample

Raises:

ValueError – If horizon is not positive.

class Dataset(*, seed: int | None = None)

Bases: abc.ABC

Abstract base class for ML datasets

Initialise the dataset.

Parameters:

seed (int | None) – Seed for the random number generator

property seed: int | None

Return the configured random seed.

Returns:

The seed passed at construction time.

Return type:

int | None

abstractmethod generate(npoints: int) → DatasetSample

Generate npoints samples from the dataset.

Parameters:

npoints (int) – Number of time steps to produce.

Returns:

The generated (inputs, targets) pair.

Return type:

DatasetSample

classmethod draw(sample: DatasetSample | FloatArray, style: str | None = None, *, config: qilisdk.utils.visualization.style.DatasetStyle | None = None, transform: qilisdk.utils.visualization.dataset_renderers.Transform | None = None, filepath: str | None = None) → None

Render a generated DatasetSample, or a raw series, with matplotlib.

The kind of plot is selected by style:

• "1d" – every component of the series against the sample index.

• "2d" – a phase portrait (two coordinates).

• "3d" – a three-dimensional phase portrait (three coordinates).

What each axis shows is decided by a transform: a callable mapping the full (n_points, n_components) series to the coordinates to plot. It may reshape, slice or delay-embed the data, not merely select columns. If none is given, the dataset’s per-mode transform (_DRAW_TRANSFORMS) is used, and failing that a dimension-based default (the first components, or a delay embedding of a one-dimensional series).

The plot’s appearance (theme, fonts, colours, grid, …) is controlled independently via config, mirroring how ScheduleStyle and CircuitStyle customise schedule and circuit plots. Each dataset may tailor the defaults of a given mode via _DRAW_STYLE_DEFAULTS; any field you set explicitly on config overrides those defaults.

Parameters:

• sample (DatasetSample | FloatArray) –

  A sample produced by generate(), of which the inputs are plotted, or an array holding the series to plot directly – so that just one half of a sample can be drawn:

  inputs, targets = MackeyGlass(tau=17.0).generate(2000)
  MackeyGlass.draw(inputs, style="1d")
  

  The array is either one-dimensional or shaped (n_points, n_components).

• style (str | None) – Plot mode, one of "1d", "2d" or "3d". Defaults to the dataset’s natural mode.

• config (DatasetStyle | None) – Visual style configuration. Defaults to DatasetStyle, merged over the dataset’s per-mode defaults.

• transform (Transform | None) –

  Callable mapping the series to the coordinates to plot, overriding the dataset’s default view. Returns two arrays for "2d", three for "3d", or any number of lines for "1d", each optionally paired with an axis label:

  Lorenz.draw(sample, style="2d", transform=lambda d: [("x", d[:, 0]), ("z", d[:, 2])])
  

• filepath (str | None) – If given, the figure is saved to this path (format inferred from the extension) instead of being shown.