lightonopu.opu

This module contains the OPU class, the main class of the library

class OPU(n_components: int = 200000, opu_device: Union[lightonopu.device.OpuDevice, lightonopu.simulated_device.SimulatedOpuDevice, None] = None, max_n_features: int = 1000, config_file: str = '', config_override: dict = None, verbose_level: int = 0, input_roi_strategy: lightonopu.types.InputRoiStrategy = <InputRoiStrategy.auto: 3>, open_at_init: bool = None)[source]

Interface to the OPU.

\[\mathbf{y} = \lvert \mathbf{R} \mathbf{x} \rvert^2\]

Main methods are transform1d and transform2d, and accept NumPy arrays or PyTorch tensors.

Acquiring/releasing hardware device resources is done by open/close and a context-manager interface.

Unless open_at_init=False, these resources are acquired automatically at init. If another process has not released the resources, an error will be raised, call close() or shutdown on the OPU object to release it.

Parameters
  • n_components (int,) – dimensionality of the target projection space.

  • opu_device (OpuDevice or SimulatedOpuDevice, optional) – optical processing unit instance linked to a physical or simulated device. If not provided, a device is properly instantiated. If opu_device is of type SimulatedOpuDevice, the random matrix is generated at __init__, using max_n_features and n_components

  • max_n_features (int, optional) – maximum number of binary features that the OPU will transform used only if opu_device is a SimulatedOpuDevice, in order to initiate the random matrix

  • config_file (str, optional) – path to the configuration file (for dev purpose)

  • config_override (dict, optional) – for override of the config_file (for dev purpose)

  • verbose_level (int, optional) – 0, 1 or 2. 0 = no messages, 1 = most messages, and 2 = messages from OPU device (very verbose).

  • input_roi_strategy (types.InputRoiStrategy, optional) – describes how to display the features on the input device @see types.InputRoiStrategy

  • open_at_init (bool, optional) – forces the setting of acquiring hardware resource at init. If not provided, follow system’s setting (usually True)

n_components

dimensionality of the target projection space.

Type

int

max_n_features

maximum number of binary features that the OPU will transform writeable only if opu_device is a SimulatedOpuDevice, in order to initiate or resize the random matrix

Type

int

device

underlying hardware that performs transformation (read-only)

Type

OpuDevice or SimulatedOpuDevice

input_roi_strategy

describes how to display the features on the input device

Type

types.InputRoiStrategy, optional

verbose_level

0, 1 or 2. 0 = no messages, 1 = most messages, and 2 = messages

Type

int, optional

close()[source]

Releases hardware resources used by the OPU device

config

Returns the internal configuration object

online_transform(n_features: Union[int, Tuple[int]])[source]

Activates the “online mode”, allowing faster transforms of single vectors

open()[source]

Acquires hardware resources used by the OPU device

@see close() or use the context manager interface for closing at the end af an indent block

transform1d(X, packed: bool = False, input_roi_: Tuple[Tuple[int, int], Tuple[int, int]] = None, context: Optional[lightonopu.context.Context] = <lightonopu.context.Context object>, raw_output_size: bool = False)[source]

Performs the nonlinear random projections of one 1d input vector, or a batch of 1d input vectors.

The input data can be bit-packed, where n_features = 8*X.shape[-1] Otherwise n_features = X.shape[-1]

If tqdm module is available, it is used for progress display

Parameters
  • X (np.ndarray or torch.Tensor) – a 1d input vector, or batch of 1d input_vectors, binary encoded, packed or not batch can be 1d or 2d. In all cases output.shape[:-1] = X.shape[:-1]

  • packed (bool, optional) – whether the input data is in bit-packed representation defaults to False

  • input_roi (if provided, as (offset, size), will override the computation of) – the input ROI (advanced parameter)

  • context (Context, optional) – will be filled with information about transform @see lightonopu.context.Context

  • raw_output_size (bool, optional) – If True, don’t cut output size at n_components (advanced parameter)

Returns

Y – complete array of nonlinear random projections of X, of size self.n_components

Return type

np.ndarray or torch.Tensor

transform2d(X, packed: bool = False, n_2d_features=None, input_roi_: Tuple[Tuple[int, int], Tuple[int, int]] = None, context: Optional[lightonopu.context.Context] = <lightonopu.context.Context object>, raw_output_size: bool = False)[source]

Performs the nonlinear random projections of one 2d input vector, or a batch of 2d input vectors.

If tqdm module is available, it is used for progress display

Parameters
  • X (np.ndarray or torch.Tensor) – a 2d input vector, or batch of 2d input_vectors, binary encoded, packed or not

  • packed (bool, optional) – whether the input data is in bit-packed representation if True, each input vector is assumed to be a 1d array, and the “real” number of features must be provided as n_2d_features defaults to False

  • n_2d_features (list, tuple or np.ndarray of length 2) – If the input is bit-packed, specifies the shape of each input vector. Not needed if the input isn’t bit-packed.

  • input_roi (if provided, as (offset, size), will override the computation of) – the input ROI (advanced parameter)

  • context (Context, optional) – will be filled with information about transform @see lightonopu.context.Context

  • raw_output_size (bool, optional) – If True, don’t cut output size at n_components (advanced parameter)

Returns

Y – complete array of nonlinear random projections of X, of size self.n_components

Return type

np.ndarray or torch.Tensor

version()[source]

Returns a multi-line string containing name and versions of the OPU

Copyright (c) 2020 LightOn, All Rights Reserved. This file is subject to the terms and conditions defined in file ‘LICENSE.txt’, which is part of this source code package.

Module containing enums used with opu.OPU class

class FeaturesFormat[source]

Strategy used for the formatting of data on the input device

auto = 3

Automatic choice

lined if features are 1d, macro_2d if 2d

lined = 1

Features are positioned in line

macro_2d = 2

Features are zoomed into elements

none = 4

No formatting

input is displayed as-is, but it must match the same number of elements of the input device

class InputRoiStrategy[source]

Strategy used for computing the input ROI

auto = 3

Try to find the most appropriate between these two modes

full = 1

Apply zoom on elements to fill the whole display

small = 2

Center the features on the display, with one-to-one element mapping

class OutputRoiStrategy[source]

Strategy used for computing the output ROI

mid_square = 2

Area in the middle & square (Saturn)

mid_width = 1

Area in the middle & max_width, to have max speed (Zeus, Vulcain)

class Context(frametime: int = None, exposure: int = None, output_roi: Tuple[Tuple[int, int], Tuple[int, int]] = None, start: datetime.datetime = None, end: datetime.datetime = None, gain: float = None, input_roi: Tuple[Tuple[int, int], Tuple[int, int]] = None, n_ones: int = None, fmt_type: lightonopu.types.FeaturesFormat = None, fmt_factor: int = None)[source]

Describes the context of an OPU transform

exposure_us

Exposure time of the output device (µs)

Type

int

frametime_us

Exposure time of the input device (µs)

Type

int

output_roi

(offset, size) of the output device region of interest

Type

tuple(tuple(int))

input_roi

(offset, size) of the input device region of interest

start

epoch of the start time of the transform

Type

float

end

epoch of the end time of the transform

Type

float

n_ones

average number of ones displayed on the input device

Type

int

self.fmt_type

type of formatting used to map features to the input device

Type

lightonopu.types.FeaturesFormat

self.fmt_factor

size of the macro-elements used when formatting

Type

int

static from_dict(d)[source]

Create a context from a dict (flat or not)

from_opu(opu, start: datetime.datetime, end: datetime.datetime = None)[source]

Takes context from an OPU device, namely frametime, exposure, cam_roi and gain. With optional end time

from_epoch(datetime_or_epoch)[source]

Convert to datetime if argument is an epoch, otherwise return same