API Reference: hxtorch

hxtorch from Python

hxtorch.nn.Conv1d : public hxtorch.nn.ConvNd , public torch.nn.Conv1d

Applies a 1D convolution over an input signal composed of several input
planes.

Subclassed by hxtorch.nn.ExpandedConv1d

Public Functions

__init__(self, Integral in_channels, Integral out_channels, Union[Integral, Tuple[Integral]] kernel_size, Integral stride=1, Union[Integral, Tuple[Integral, Integral]] padding=0, Union[Integral, Tuple] dilation=1, Integral groups=1, bool bias=True, str padding_mode='zeros', Optional[Integral] num_sends=None, Integral wait_between_events=defaults.wait_between_events, bool mock=False, *Optional[Callable[[torch.Tensor], torch.Tensor]] input_transform=None, Optional[Callable[[torch.Tensor], torch.Tensor]] weight_transform=clamp_weight_)

:param in_channels: Number of channels in the input
:param out_channels: Number of channels produced by the convolution
:param kernel_size: Size of the convolving kernel
:param stride: Stride of the convolution
:param padding: Zero-padding added to both sides of the input
:param padding_mode: 'zeros', 'reflect', 'replicate' or 'circular'
:param dilation: Spacing between kernel elements
:param groups: Number of blocked connections from input channels to
    output channels
:param bias: If ``True``, adds a learnable bias to the output
:param num_sends: Number of sends of the input. Values greater than 1
    result in higher output to the neurons and increases the s/n ratio.
    For ``None`` this is automatically adjusted during initialization.
:param wait_between_events: Wait time between two successive vector
    inputs, in FPGA clock cycles.
    Shorter wait time can lead to saturation of the synaptic input.
:param mock: Enable mock mode.
:param input_transform: Function that receives the input and returns
    a tensor to be used as input to the chip.
:param weight_transform: Function that receives the weight and returns
    a tensor to be used as weight matrix on the chip.

__repr__(self)

forward(self, input)

reset_parameters(self, Real weight_mean=0., Integral relu_shift=1)

Reset parameters to reasonable initialization values. Method based on
*Delving deep into rectifiers: Surpassing human-level performance on
ImageNet classification* - He, K. et al. (2015)

:param weight_mean: Mean value of the weight distribution
:param relu_shift: Bit shift assumed in subsequent ConvertingReLU

Public Members

input_transform

mock

num_sends

padding_mode

wait_between_events

weight_transform

Private Members

_conv

hxtorch.nn.Conv2d : public hxtorch.nn.ConvNd , public torch.nn.Conv2d

Applies a 2D convolution over an input image composed of several input
planes.

Public Functions

__init__(self, Integral in_channels, Integral out_channels, Union[Integral, Tuple[Integral, Integral]] kernel_size, Integral stride=1, Union[Integral, Tuple[Integral, Integral]] padding=0, Integral dilation=1, Integral groups=1, bool bias=True, str padding_mode='zeros', Optional[Integral] num_sends=None, Integral wait_between_events=defaults.wait_between_events, bool mock=False, *Optional[Callable[[torch.Tensor], torch.Tensor]] input_transform=None, Optional[Callable[[torch.Tensor], torch.Tensor]] weight_transform=clamp_weight_)

:param in_channels: Number of channels in the input
:param out_channels: Number of channels produced by the convolution
:param kernel_size: Size of the convolving kernel
:param stride: Stride of the convolution
:param padding: Zero-padding added to both sides of the input
:param padding_mode: 'zeros', 'reflect', 'replicate' or 'circular'
:param dilation: Spacing between kernel elements
:param groups: Number of blocked connections from input channels to
    output channels
:param bias: If ``True``, adds a learnable bias to the output
:param num_sends: Number of sends of the input. Values greater than 1
    result in higher output to the neurons and increases the s/n ratio.
    For ``None`` this is automatically adjusted during initialization.
:param mock: Enable mock mode.
:param wait_between_events: Wait time between two successive vector
    inputs, in FPGA clock cycles.
    Shorter wait time can lead to saturation of the synaptic input.
:param input_transform: Function that receives the input and returns
    a tensor to be used as input to the chip.
:param weight_transform: Function that receives the weight and returns
    a tensor to be used as weight matrix on the chip.

__repr__(self)

forward(self, input)

reset_parameters(self, Real weight_mean=0., Integral relu_shift=1)

Reset parameters to reasonable initialization values. Method based on
*Delving deep into rectifiers: Surpassing human-level performance on
ImageNet classification* - He, K. et al. (2015)

:param weight_mean: Mean value of the weight distribution
:param relu_shift: Bit shift assumed in subsequent ConvertingReLU

Public Members

input_transform

mock

num_sends

padding_mode

wait_between_events

weight_transform

Private Members

_conv

hxtorch.nn.ConvertingReLU : public hxtorch.nn.ReLU

Applies a rectified linear unit to the input, shifts and clips to the
input range of the chip.

Public Functions

__init__(self, Integral shift=2, bool mock=False)

:param shift: Number of bits the result is shifted by
:param mock: Enable mock mode

__repr__(self)

forward(self, torch.Tensor input)

Public Members

mock

shift

hxtorch.nn.ConvNd : public hxtorch.nn.MACLayer , public torch.nn.modules.conv._ConvNd

Base class for n-dimensional convolution.

Subclassed by hxtorch.nn.Conv1d, hxtorch.nn.Conv2d

Public Functions

__repr__(self)

forward(self, input)

reset_parameters(self, Real weight_mean=0., Integral relu_shift=1)

Reset parameters to reasonable initialization values. Method based on
*Delving deep into rectifiers: Surpassing human-level performance on
ImageNet classification* - He, K. et al. (2015)

:param weight_mean: Mean value of the weight distribution
:param relu_shift: Bit shift assumed in subsequent ConvertingReLU

Public Members

input_transform

mock

num_sends

padding_mode

wait_between_events

weight_transform

Private Functions

_conv(self, torch.Tensor input, torch.Tensor weight, torch.Tensor bias, Tuple[Integral, ...] stride, **kwargs)

Implementation of convolution function.

hxtorch.nn.ExpandedConv1d : public hxtorch.nn.Conv1d

Unrolls the weight matrix for execution on hardware.
This maximizes the use of the synapses array.

Caveat:
Fixed-pattern noise cannot be individually compensated for during
training, because the same weights are used at different locations!

Public Functions

__init__(self, int in_channels, int out_channels, Union[int, Tuple[int]] kernel_size, int stride=1, Union[int, Tuple[int, int]] padding=0, Union[int, Tuple] dilation=1, int groups=1, bool bias=True, str padding_mode='zeros', Optional[int] num_sends=None, int wait_between_events=defaults.wait_between_events, bool mock=False, *Optional[Callable[[torch.Tensor], torch.Tensor]] input_transform=None, Optional[Callable[[torch.Tensor], torch.Tensor]] weight_transform=clamp_weight_, Optional[int] num_expansions=None)

:param in_channels: Number of channels in the input
:param out_channels: Number of channels produced by the convolution
:param kernel_size: Size of the convolving kernel
:param stride: Stride of the convolution
:param padding: Zero-padding added to both sides of the input
:param padding_mode: 'zeros', 'reflect', 'replicate' or 'circular'
:param dilation: Spacing between kernel elements
:param groups: Number of blocked connections from input channels to
    output channels
:param bias: If ``True``, adds a learnable bias to the output
:param num_sends: Number of sends of the input. Values greater than 1
    result in higher output to the neurons and increases the s/n ratio.
    For ``None`` this is automatically adjusted during initialization.
:param wait_between_events: Wait time between two successive vector
    inputs, in FPGA clock cycles.
    Shorter wait time can lead to saturation of the synaptic input.
:param mock: Enable mock mode.
:param input_transform: Function that receives the input and returns
    a tensor to be used as input to the chip.
:param weight_transform: Function that receives the weight and returns
    a tensor to be used as weight matrix on the chip.
:param num_expansions: Number of enrolled kernels in a single operation

__repr__(self)

extra_repr(self)

forward(self, input)

reset_parameters(self, Real weight_mean=0., Integral relu_shift=1)

Reset parameters to reasonable initialization values. Method based on
*Delving deep into rectifiers: Surpassing human-level performance on
ImageNet classification* - He, K. et al. (2015)

:param weight_mean: Mean value of the weight distribution
:param relu_shift: Bit shift assumed in subsequent ConvertingReLU

Public Members

input_transform

mock

num_expansions

num_sends

padding_mode

wait_between_events

weight_transform

Private Functions

_conv(self, *args, **kwargs)

class hxtorch.nn.Layer

Base class of all layers in :mod:`hxtorch.nn`.

Subclassed by hxtorch.nn.MACLayer, hxtorch.nn.ReLU

Public Functions

__init__(self, bool mock=False)

:param mock: Enable mock mode.

__repr__(self)

Public Members

mock

hxtorch.nn.Linear : public hxtorch.nn.MACLayer , public torch.nn.Linear

Applies a linear transformation to the incoming data on Hicann-X.

Public Functions

__init__(self, Integral in_features, Integral out_features, bool bias=True, Optional[Integral] num_sends=None, Integral wait_between_events=defaults.wait_between_events, bool mock=False, *Integral avg=1, Optional[Callable[[torch.Tensor], torch.Tensor]] input_transform=None, Optional[Callable[[torch.Tensor], torch.Tensor]] weight_transform=clamp_weight_)

:param in_features: Size of each input sample
:param out_features: Size of each output sample
:param bias: If set to `True`, the layer will learn an additive bias.
:param num_sends: Number of sends of the input. Values greater than 1
    result in higher output to the neurons and increases the s/n ratio.
    For ``None`` this is automatically adjusted during initialization.
:param wait_between_events: Wait time between two successive vector
    inputs, in FPGA clock cycles.
    Shorter wait time can lead to saturation of the synaptic input.
:param mock: Enable mock mode.
:param avg: Number of neurons to average over. This option is targeted
    at reducing statistical noise.
    Beware: We average over different fixed-pattern instances, but they
    are all configured at the same weight, so they are not trained
    individually. This could potentially have negative implications.
:param input_transform: Function that receives the input and returns
    a tensor to be used as input to the chip.
:param weight_transform: Function that receives the weight and returns
    a tensor to be used as weight matrix on the chip.

__repr__(self)

forward(self, input)

reset_parameters(self, Real weight_mean=0., Integral relu_shift=1)

Reset parameters to reasonable initialization values. Method based on
*Delving deep into rectifiers: Surpassing human-level performance on
ImageNet classification* - He, K. et al. (2015)

:param weight_mean: Mean value of the weight distribution
:param relu_shift: Bit shift assumed in subsequent ConvertingReLU

Public Members

avg

input_transform

mock

num_sends

wait_between_events

weight_transform

Private Members

_matmul

hxtorch.nn.MACLayer : public hxtorch.nn.Layer

Layer that performs a multiply accumulate operation.

Subclassed by hxtorch.nn.ConvNd, hxtorch.nn.Linear

Public Functions

__init__(self, Optional[Integral] num_sends=None, Integral wait_between_events=defaults.wait_between_events, bool mock=False, *Optional[Callable[[torch.Tensor], torch.Tensor]] input_transform=None, Optional[Callable[[torch.Tensor], torch.Tensor]] weight_transform=clamp_weight_)

:param num_sends: Number of sends of the input. Values greater than 1
    result in higher output to the neurons and increases the s/n ratio.
    For ``None`` this is automatically adjusted during initialization.
:param wait_between_events: Wait time between two successive vector
    inputs, in FPGA clock cycles.
    Shorter wait time can lead to saturation of the synaptic input.
:param mock: Enable mock mode.
:param input_transform: Function that receives the input and returns
    a tensor to be used as input to the chip.
:param weight_transform: Function that receives the weight and returns
    a tensor to be used as weight matrix on the chip.

__repr__(self)

reset_parameters(self, Real weight_mean=0., Integral relu_shift=1)

Reset parameters to reasonable initialization values. Method based on
*Delving deep into rectifiers: Surpassing human-level performance on
ImageNet classification* - He, K. et al. (2015)

:param weight_mean: Mean value of the weight distribution
:param relu_shift: Bit shift assumed in subsequent ConvertingReLU

Public Members

input_transform

mock

num_sends

wait_between_events

weight_transform

mnist.MNIST : public torch.utils.data.TensorDataset

 The MNIST dataset

Public Functions

__init__(self, root, train)

:param root: Root directory of the dataset that contains
    `MNIST/processed/training.pt` and  `MNIST/processed/test.pt`.
:param train: If True, creates dataset from `training.pt`, otherwise
    from `test.pt`.

mnist.Model : public torch.nn.Module

Simple CNN model to classify written digits from the MNIST database.

Model topology:
    - Conv2d with 10x10 kernel, stride 5
    - Linear layer with 128 hidden neurons

Public Functions

__init__(self, bool mock)

:param mock: Whether to use a software simulation instead of the ASIC.

forward(self, *x)

Public Members

classifier

features

hxtorch.nn.ReLU : public hxtorch.nn.Layer , public torch.nn.ReLU

Applies a rectified linear unit to the input.

Subclassed by hxtorch.nn.ConvertingReLU

Public Functions

__init__(self, bool mock=False)

:param mock: Enable mock mode

__repr__(self)

forward(self, torch.Tensor input)

Public Members

mock

module _hxtorch

module hxtorch

Variables

level

module hxtorch.nn

This module contains layers that can be used in modules together
with the building blocks from py:mod:`torch.nn`. Unlike their counterparts,
their multiply-accumulate operations are performed with the
BrainScaleS-2 accelerator. Additional digital operations are performed
in the SIMD processors of BSS-2.

Functions

clamp_weight_(torch.Tensor weight)

Clamps all elements of the weight in-place into the maximal weight range
of BrainScaleS-2.

scale_input(torch.Tensor x_in)

Scales the tensor to the maximal input range of BrainScaleS-2.

scale_weight(torch.Tensor weight)

Scales the tensor to the maximal weight range of BrainScaleS-2.

module minimal

A minimal example that multiplies a vector and a matrix.

Functions

main()

module mnist

Training example for the MNIST handwritten-digits dataset using a host machine
with the BrainScaleS-2 ASIC in the loop.

Functions

get_parser()

Returns an argument parser with all the options.

init(str calibration_path, bool mock, Real mock_noise_std, Real mock_gain)

Initialize hxtorch connection and load calibration.

Caveat: This also measures and sets the gain, therefore do this before
initializing the model (as this influences layer initialization).

:param calibration_path: Path of custom calibration
:param mock: Whether to simulate the hardware
:param mock_noise_std: Standard deviation of artificial noise in mock mode
:param mock_gain: Multiplication gain used in mock mode

main(argparse.Namespace args)

The main experiment function.

:param args: Command-line arguments

shrink_dataset(torch.utils.data.Dataset dataset, Real fraction)

 Returns a fraction of the original dataset

test(torch.nn.Module model, torch.utils.data.DataLoader loader)

Test the model.

:param model: The model to test
:param loader: Data loader containing the test data set
:returns: Test accuracy

train(torch.nn.Module model, torch.utils.data.DataLoader loader, torch.optim.Optimizer optimizer)

Train the model.

:param model: The model
:param loader: Data loader containing the train data set
:param optimizer: Optimizer that handles the weight updates

Variables

log = hxtorch.logger.get("hxtorch.examples.mnist")

namespace std

STL namespace.

namespace torch

namespace nn

namespace modules

namespace conv

namespace utils

namespace data

file __init__.py

file minimal.py

file mnist.py

file nn.py

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch/src/pyhxtorch/hxtorch/examples

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch/src/pyhxtorch/hxtorch

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch/src/pyhxtorch

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch/src

hxtorch from C++

struct hxtorch::CalibrationPath

#include <connection.h>

Path to a calibration.

Public Functions

inline explicit CalibrationPath(std::string value)

Public Members

std::string value

template<typename R, typename Trafo, typename T, size_t N, template<typename U> class PtrTraits, typename index_t>
struct hxtorch::detail::ConvertToVector

#include <util.h>

Implementation for the at::TensorAccessor<T, N, PtrTraits, index_t> to std::vector<…<R>> (nesting-level N) conversion helper below.

Note

Other template parameaters come from at::TensorAccessor

tparam R

return value type

tparam Trafo

transformation function

Public Types

typedef std::vector<typename unpacked_type::result_type> result_type

typedef at::TensorAccessor<T, N, PtrTraits, index_t> value_type

Public Static Functions

static inline result_type apply(value_type const &value, Trafo t)

Private Types

typedef ConvertToVector<R, Trafo, T, N - 1, PtrTraits, index_t> unpacked_type

template<typename R, typename Trafo, typename T, template<typename U> class PtrTraits, typename index_t>
struct hxtorch::detail::ConvertToVector<R, Trafo, T, 1, PtrTraits, index_t>

#include <util.h>

Public Types

typedef std::vector<R> result_type

typedef at::TensorAccessor<T, 1, PtrTraits, index_t> value_type

Public Static Functions

static inline result_type apply(value_type const &value, Trafo t)

struct hxtorch::HWDBPath

#include <connection.h>

Path to a hardware database.

Public Functions

inline explicit HWDBPath(std::optional<std::string> path = std::nullopt, std::string version = "stable/latest")

Public Members

std::optional<std::string> path

std::string version

struct hxtorch::detail::InferenceTracer

#include <inference_tracer.h>

Inference tracer implementation.

Currently only traces operation names.

Public Functions

void check_input(torch::Tensor const &value) const

Check input is equal to saved output.

Allows to ensure that between two traecd operations, the data is modified only by an identity function and thus all not-traced operations in between can be discarded.

Parameters

value – Value to check

void update_output(torch::Tensor const &value)

Update cached output value.

This is compared with the input of the next traced operation to ensure no modifications in-between.

Parameters

value – Value to update

Public Members

std::vector<std::string> operation_names

grenade::vx::compute::Sequence ops

Private Members

std::optional<torch::Tensor> m_last_output

Last output tensor to compare to next operations input tensor for sanity check.

class hxtorch::InferenceTracer

#include <inference_tracer.h>

Inference tracer for a linear sequence of operations.

The traced operations’ state is saved as a grenade::compute::Sequence, which can be executed as a single operation without transformation to and from PyTorch tensors. It is ensured, that no untraced modifications are made in-between traced operations by comparing the last traced operation’s output with the currently traced operation’s input value.

Note

Not final API or implementation, see Issue #3694

Public Functions

InferenceTracer(std::string const &filename)

Construct inference tracer with filename to store traced operations to.

void start()

Start tracing operations by registering tracer.

std::vector<std::string> stop()

Stop tracing operations by deregistering tracer and save traced operations to given file.

Returns

List of traced operation names

Private Members

std::string m_filename

std::shared_ptr<detail::InferenceTracer> m_impl

class hxtorch::MAC : public torch::autograd::Function<MAC>

#include <mac.h>

Public Static Functions

static torch::autograd::variable_list backward(torch::autograd::AutogradContext *ctx, torch::autograd::variable_list grad_output)

static torch::autograd::variable_list forward(torch::autograd::AutogradContext *ctx, torch::autograd::Variable x, torch::autograd::Variable weights, int64_t num_sends, int64_t wait_between_events, bool mock)

struct hxtorch::MockParameter

#include <mock.h>

Parameter of hardware mock.

Public Functions

MockParameter() = default

Default constructor.

inline MockParameter(double noise_std, double gain)

Construct with noise standard deviation and gain.

Parameters

• noise_std – Noise standard deviation to use

• gain – Gain to use

Public Members

double gain = constants::defaults::gain

double noise_std = constants::defaults::noise_std

struct hxtorch::detail::MultidimIterator

#include <iterator.h>

Public Functions

inline MultidimIterator(std::vector<int64_t> const &range)

inline MultidimIterator end() const

inline bool operator!=(MultidimIterator const &other) const

inline std::vector<int64_t> operator*() const

inline MultidimIterator &operator++()

inline bool operator==(MultidimIterator const &other) const

Private Members

std::vector<int64_t> m_range

std::vector<int64_t> m_state

namespace grenade

namespace vx

namespace hxtorch

Functions

torch::Tensor add(torch::Tensor const &input, torch::Tensor const &other, double alpha = 1., bool mock = false)

Elementwise addition operating on int8 value range.

Parameters

• input – Input tensor

• other – Other tensor, which must be broadcastable to input tensor dimension

• alpha – The scalar multiplier for other

• mock – Enable mock mode

torch::Tensor argmax(torch::Tensor const &input, c10::optional<int64_t> dim = c10::nullopt, bool keepdim = false, bool mock = false)

Arg max operation on int8 value range.

Parameters

• input – The input tensor

• dim – The dimension to reduce. If unspecified, the argmax of the flattened input is returned.

• keepdim – Whether the output tensor has dim retained or not. Ignored if dim is unspecified.

• mock – Enable mock mode

Returns

The indices of the maximum values of a tensor across a dimension

torch::Tensor conv1d(torch::Tensor const &input, torch::Tensor const &weight, c10::optional<torch::Tensor> const &bias, int64_t stride = 1, int64_t num_sends = 1, int64_t wait_between_events = hxtorch::constants::defaults::wait_between_events, bool mock = false)

torch::Tensor conv1d(torch::Tensor const &input, torch::Tensor const &weight, c10::optional<torch::Tensor> const &bias, std::array<int64_t, 1> stride, int64_t num_sends = 1, int64_t wait_between_events = hxtorch::constants::defaults::wait_between_events, bool mock = false)

torch::Tensor conv2d(torch::Tensor const &input, torch::Tensor const &weight, c10::optional<torch::Tensor> const &bias, int64_t stride = 1, int64_t num_sends = 1, int64_t wait_between_events = hxtorch::constants::defaults::wait_between_events, bool mock = false)

torch::Tensor conv2d(torch::Tensor const &input, torch::Tensor const &weight, c10::optional<torch::Tensor> const &bias, std::array<int64_t, 2> stride, int64_t num_sends = 1, int64_t wait_between_events = hxtorch::constants::defaults::wait_between_events, bool mock = false)

template<typename R, typename T, size_t N, template<typename U> class PtrTraits, typename index_t, typename Trafo = decltype(detail::default_transform<R, T>)>
detail::ConvertToVector<R, Trafo, T, N, PtrTraits, index_t>::result_type convert_to_vector(at::TensorAccessor<T, N, PtrTraits, index_t> const &tensor, Trafo func = detail::default_transform)

Conversion helper for converting at::TensorAccessor<T, N, PtrTraits, index_t> to std::vector<…<R>> (nesting-level N) types.

Note

The underlying value_type T is converted to R. All other template parameters come from at::TensorAccessor

Template Parameters

• R – value_type to be returned

• Trafo – Conversion type (defaults to R)

Parameters

• tensor – The tensor accessor to be converted to a nested vector

• func – The conversion function for the value_type inside (defaults to R())

Returns

A nested std::vector<std::vector<…<R>>> (N nested vectors).

torch::Tensor converting_relu(torch::Tensor const &input, int64_t shift = 2, bool mock = false)

Rectified linear unit operating on int8 value range converting to uint5 value range.

The result is bit-shifted by shift after applying the ReLU and clipped to the input range of BrainScaleS-2.

Parameters

• input – Input tensor

• shift – Amount of bits to shift before clipping

• mock – Enable mock mode

torch::Tensor expanded_conv1d(torch::Tensor const &input, torch::Tensor const &weight, c10::optional<torch::Tensor> const &bias, int64_t stride = 1, int64_t num_expansions = 1, int64_t num_sends = 1, int64_t wait_between_events = hxtorch::constants::defaults::wait_between_events, bool mock = false)

1D convolution operation that unrolls the weight matrix for execution on hardware.

This maximizes the use of the synapses array.

Note

Fixed-pattern noise cannot be individually compensated for during training, because the same weights are used at different locations!

Parameters

• input – Input tensor of shape (minibatch, in_channels, iW)

• weight – Filters of shape (out_channels, in_channels / groups, kW)

• bias – Optional bias of shape (out_channels)

• stride – Stride of the convolving kernel

• num_expansions – Number of enrolled kernels that will be placed side by side in a single operation

• num_sends – How often to send the (same) input vector

• wait_between_events – How long to wait (in FPGA cycles) between events

• mock – Enable mock mode

torch::Tensor expanded_conv1d(torch::Tensor const &input, torch::Tensor const &weight, c10::optional<torch::Tensor> const &bias, std::array<int64_t, 1> stride, int64_t num_expansions = 1, int64_t num_sends = 1, int64_t wait_between_events = hxtorch::constants::defaults::wait_between_events, bool mock = false)

lola::vx::v3::Chip get_chip()

Get copy of ChipConfig object.

MockParameter get_mock_parameter()

torch::Tensor inference_trace(torch::Tensor const &input, std::string const &filename)

Execute inference of stored trace.

Parameters

• input – Input data to use

• filename – Filename to serialized operation trace

void init_hardware(CalibrationPath const &calibration_path)

Initialize the hardware with calibration path.

Parameters

calibration_path – Calibration path to load from

void init_hardware(std::optional<HWDBPath> const &hwdb_path = std::nullopt, bool spiking = false)

Initialize the hardware automatically from the environment.

Parameters

• calibration_version – Calibration version to load

• hwdb_path – Optional path to the hwdb to use

void init_hardware_minimal()

Initialize automatically from the environment without ExperimentInit and without any calibration.

torch::Tensor mac(torch::Tensor const &x, torch::Tensor const &weights, int64_t num_sends = 1, int64_t wait_between_events = wait_between_events, bool mock = false)

The bare mutliply-accumulate operation of BrainScaleS-2.

A 1D input x is multiplied by the weight matrix weights. If x is two-dimensional, the weights are sent only once to the synapse array and the inputs are consecutively multiplied as a 1D vector.

Parameters

• x – Input tensor

• weights – The weights of the synapse array

• num_sends – How often to send the (same) input vector

• wait_between_events – How long to wait (in FPGA cycles) between events

• mock – Enable mock mode

Returns

Resulting tensor

torch::Tensor matmul(torch::Tensor const &input, torch::Tensor const &other, int64_t num_sends = 1, int64_t wait_between_events = wait_between_events, bool mock = false)

Drop-in replacement for the torch.matmul operation that uses BrainScaleS-2.

Note

The current implementation only supports other to be 1D or 2D.

Parameters

• input – First input tensor

• other – Second input tensor

• num_sends – How often to send the (same) input vector

• wait_between_events – How long to wait (in FPGA cycles) between events

• mock – Enable mock mode

Returns

Resulting tensor

MockParameter measure_mock_parameter()

void release_hardware()

Release hardware resource.

torch::Tensor relu(torch::Tensor const &input, bool mock = false)

Rectified linear unit operating on int8 value range.

Parameters

• input – Input tensor

• mock – Enable mock mode

void set_mock_parameter(MockParameter const &parameter)

namespace hxtorch::constants

Variables

static constexpr static intmax_t hardware_matrix_height  =halco::hicann_dls::vx::v3::SynapseRowOnSynram::size / 2

static constexpr static intmax_t hardware_matrix_width  =halco::hicann_dls::vx::v3::SynapseOnSynapseRow::size

static constexpr static intmax_t input_activation_max   = grenade::vx::UInt5::max

static constexpr static intmax_t input_activation_min   = grenade::vx::UInt5::min

static constexpr static intmax_t output_activation_max  =std::numeric_limits<grenade::vx::Int8::value_type>::max()

static constexpr static intmax_t output_activation_min  =std::numeric_limits<grenade::vx::Int8::value_type>::min()

static constexpr static intmax_t synaptic_weight_max   = grenade::vx::compute::MAC::Weight::max

static constexpr static intmax_t synaptic_weight_min   = grenade::vx::compute::MAC::Weight::min

namespace hxtorch::constants::defaults

Variables

static constexpr static double gain   = 0.002

static constexpr static double noise_std   = 2.

static constexpr static intmax_t wait_between_events   = 5

namespace hxtorch::detail

Functions

torch::autograd::variable_list add_backward(torch::Tensor const &grad_output, torch::Tensor const &input, torch::Tensor const &other)

torch::Tensor add_forward(torch::Tensor const &input, torch::Tensor const &other)

torch::Tensor add_mock_forward(torch::Tensor const &input, torch::Tensor const &other)

torch::Tensor argmax(torch::Tensor const &input, c10::optional<int64_t> dim = c10::nullopt, bool keepdim = false)

torch::Tensor argmax_mock(torch::Tensor const &input, c10::optional<int64_t> dim = c10::nullopt, bool keepdim = false)

torch::Tensor conv(torch::Tensor const &input, torch::Tensor const &weights, c10::optional<torch::Tensor> const &bias, std::vector<int64_t> const &stride, std::vector<int64_t> const &dilation, int64_t num_sends, int64_t wait_between_events, bool mock)

int64_t conv1d_output_size(int64_t input_size, int64_t kernel_size, int64_t stride = 1, int64_t dilation = 1)

Returns the output size of a convolution with given input size, kernel size, stride and dilation.

std::vector<int64_t> conv_output_size(std::vector<int64_t> input_size, std::vector<int64_t> kernel_size, std::vector<int64_t> stride, std::vector<int64_t> dilation)

Returns the output size of a convolution with given input size, kernel size, stride and dilation.

grenade::vx::UInt5 convert_activation(float value)

float convert_membrane(int8_t value)

grenade::vx::compute::MAC::Weight convert_weight(float value)

torch::autograd::variable_list converting_relu_backward(torch::Tensor const &grad_output, torch::Tensor const &input, int64_t shift)

torch::Tensor converting_relu_forward(torch::Tensor const &input, int64_t shift)

torch::Tensor converting_relu_mock_forward(torch::Tensor const &input, int64_t shift)

template<typename R, typename T>
R default_transform(T const &t)

Default transformation function from T to R.

torch::Tensor expanded_conv1d(torch::Tensor const &input, torch::Tensor const &weights, c10::optional<torch::Tensor> const &bias, int64_t stride, int64_t dilation, int64_t num_expansions, int64_t num_sends, int64_t wait_between_events, bool mock)

lola::vx::v3::Chip &getChip()

Get singleton chip configuration.

Returns

Reference to chip configuration

std::unique_ptr<grenade::vx::JITGraphExecutor> &getConnection()

Get singleton connection.

Returns

Reference to connection

std::unordered_set<std::shared_ptr<InferenceTracer>> &getInferenceTracer()

Get singleton set of registered inference tracers.

MockParameter &getMockParameter()

std::unique_ptr<stadls::vx::ReinitStackEntry> &getReinitCalibration()

Get singleton calibration reinit program.

Returns

Reference to reinit stack entry holding calibration pbmem.

bool has_tracer()

Check whether inference tracers are registered.

Returns

Boolean value

torch::autograd::variable_list mac_backward(torch::Tensor grad_output, torch::Tensor x, torch::Tensor weights)

torch::Tensor mac_forward(torch::Tensor x, torch::Tensor weights, int64_t num_sends, int64_t wait_between_events)

Calculate forward-pass of multiply accumulate operation.

Input dimensions supported are 1D or 2D, where in the latter the input plane is the highest dimension and the first dimension describes which input vector to choose. The multiply accumulate therefore multiplies the last input dimension with the first weights dimension like y = x^T W.

Parameters

• x – Input (1D or 2D)

• weights – 2D weight matrix

• num_sends – How often to send the (same) input vector

Returns

Resulting tensor

torch::Tensor mac_mock_forward(torch::Tensor const &x, torch::Tensor const &weights, int64_t num_sends)

Mocks the forward-pass of the multiply accumulate operation.

Input dimensions supported are 1D or 2D, where in the latter the input plane is the highest dimension and the first dimension describes which input vector to choose. The multiply accumulate therefore multiplies the last input dimension with the first weights dimension like y = x^T W.

Parameters

• x – Input (1D or 2D)

• weights – 2D weight matrix

• num_sends – How often to send the (same) input vector

Returns

Resulting tensor

template<typename T>
auto multi_narrow(T &t, std::vector<int64_t> dim, std::vector<int64_t> start, std::vector<int64_t> length)

torch::autograd::variable_list relu_backward(torch::Tensor const &grad_output, torch::Tensor const &input)

torch::Tensor relu_forward(torch::Tensor const &input)

torch::Tensor relu_mock_forward(torch::Tensor const &input)

void tracer_add(std::string const &name, grenade::vx::compute::Sequence::Entry &&op)

Add operation to trace.

Parameters

• name – Name to use

• op – Operation to add

void tracer_check_input(torch::Tensor const &value)

Check all tracers for equality of the output of the last traced operation with the given value.

Throws

std::runtime_error – On this operations input being unequal to last operations output

Parameters

value – Value to check

void tracer_update_output(torch::Tensor const &value)

Update all tracers’ output of the last traced operation with the given value.

Parameters

value – Value to update

namespace hxtorch::snn

Functions

grenade::vx::IODataMap run(lola::vx::v3::Chip const &config, grenade::vx::network::NetworkGraph const &network_graph, grenade::vx::IODataMap const &inputs, grenade::vx::ExecutionInstancePlaybackHooks &playback_hooks)

Strips connection from grenade::vx::network::run for python exposure.

namespace lola

namespace vx

namespace v3

namespace stadls

namespace vx

namespace std

STL namespace.

namespace torch

namespace autograd

file add.h

#include <torch/torch.h>

file add.h

#include <torch/torch.h>

file argmax.h

#include <torch/torch.h>

file argmax.h

#include <torch/torch.h>

file connection.h

#include “lola/vx/v3/chip.h”#include <optional>#include <string>

file connection.h

#include <memory>

file constants.h

#include “grenade/vx/compute/mac.h”#include “grenade/vx/types.h”#include “halco/hicann-dls/vx/v3/synapse.h”#include <limits>

file conv.h

#include <array>#include <torch/torch.h>#include “hxtorch/constants.h”

file conv.h

#include <array>#include <torch/torch.h>

file conv1d.h

#include <torch/torch.h>

file conversion.h

#include “grenade/vx/compute/mac.h”#include “grenade/vx/types.h”

file inference_tracer.h

#include <memory>#include <optional>#include <string>#include <unordered_set>#include <vector>#include <torch/torch.h>#include “grenade/vx/compute/sequence.h”

file inference_tracer.h

#include <string>#include <torch/torch.h>

file iterator.h

#include <cstdint>#include <vector>

file mac.h

#include <torch/torch.h>

file mac.h

#include <torch/torch.h>#include “hxtorch/constants.h”

file mock.h

#include “hxtorch/mock.h”

file mock.h

#include “hxtorch/constants.h”

file narrow.h

#include <array>#include <torch/torch.h>

file relu.h

#include <torch/torch.h>

file relu.h

#include <torch/torch.h>

file util.h

#include <type_traits>#include <vector>#include <torch/torch.h>

file docstrings.h

Variables

static const char * __doc_hxtorch_add  =R"doc(Elementwise addition operating on int8 value range.@param input Input tensor@param other Other tensor, which must be broadcastable to input tensor dimension@param alpha The scalar multiplier for other@param mock Enable mock mode)doc"

static const char * __doc_hxtorch_argmax  =R"doc(Arg max operation on int8 value range.@param input The input tensor@param dim The dimension to reduce. If unspecified, the argmax of the flattenedinput is returned.@param keepdim Whether the output tensor has @p dim retained or not. Ignoredif @p dim is unspecified.@param mock Enable mock mode@return The indices of the maximum values of a tensor across a dimension)doc"

static const char * __doc_hxtorch_CalibrationPath   = R"doc(Path to a calibration.)doc"

static const char * __doc_hxtorch_CalibrationPath_CalibrationPath   = R"doc()doc"

static const char * __doc_hxtorch_conv1d   = R"doc()doc"

static const char * __doc_hxtorch_conv1d_2   = R"doc()doc"

static const char * __doc_hxtorch_conv2d   = R"doc()doc"

static const char * __doc_hxtorch_conv2d_2   = R"doc()doc"

static const char * __doc_hxtorch_converting_relu  =R"doc(Rectified linear unit operating on int8 value range converting to uint5value range.The result is bit-shifted by @p shift after applying the ReLU and clippedto the input range of BrainScaleS-2.@param input Input tensor@param shift Amount of bits to shift before clipping@param mock Enable mock mode)doc"

static const char * __doc_hxtorch_expanded_conv1d  =R"doc(1D convolution operation that unrolls the weight matrix for executionon hardware. This maximizes the use of the synapses array.@noteFixed-pattern noise cannot be individually compensated for duringtraining, because the same weights are used at different locations!@param input Input tensor of shape (minibatch, in_channels, *iW*)@param weight Filters of shape (out_channels, in_channels / groups, *kW*)@param bias Optional bias of shape (out_channels)@param stride Stride of the convolving kernel@param num_expansions Number of enrolled kernels that will be placed sideby side in a single operation@param num_sends How often to send the (same) input vector@param wait_between_events How long to wait (in FPGA cycles) between events@param mock Enable mock mode)doc"

static const char * __doc_hxtorch_expanded_conv1d_2   = R"doc()doc"

static const char * __doc_hxtorch_get_chip  =R"doc(Return a copy of the chip config object created at hardware initialization.@return A copy of ChipConfig object)doc"

static const char * __doc_hxtorch_get_mock_parameter  =R"doc(Returns the current mock parameters.)doc"

static const char * __doc_hxtorch_HWDBPath   = R"doc(Path to a hardware database.)doc"

static const char * __doc_hxtorch_HWDBPath_HWDBPath   = R"doc()doc"

static const char * __doc_hxtorch_inference_trace  =R"doc(Execute inference of stored trace.@param input Input data to use@param filename Filename to serialized operation trace)doc"

static const char * __doc_hxtorch_InferenceTracer  =R"doc(Inference tracer for a linear sequence of operations.The traced operations' state is saved as a grenade::compute::Sequence,which can be executed as a single operation without transformation to andfrom PyTorch tensors.It is ensured, that no untraced modifications are made in-between tracedoperations by comparing the last traced operation's output with thecurrently traced operation's input value.@noteNot final API or implementation, see Issue #3694)doc"

static const char * __doc_hxtorch_InferenceTracer_InferenceTracer  =R"doc(Construct inference tracer with filename to store traced operations to.)doc"

static const char * __doc_hxtorch_InferenceTracer_start  =R"doc(Start tracing operations by registering tracer.)doc"

static const char * __doc_hxtorch_InferenceTracer_stop  =R"doc(Stop tracing operations by deregistering tracer and save tracedoperations to given file.@return List of traced operation names)doc"

static const char * __doc_hxtorch_init_hardware  =R"doc(Initialize the hardware automatically from the environment.@param hwdb_path Optional path to the hwdb to use@param spiking Boolean flag indicating whether spiking or non-spiking calibration is loaded)doc"

static const char * __doc_hxtorch_init_hardware_2  =R"doc(Initialize the hardware with calibration path.@param calibration_path Calibration path to load from)doc"

static const char * __doc_hxtorch_init_hardware_minimal  =R"doc(Initialize automatically from the environmentwithout ExperimentInit and without any calibration.)doc"

static const char * __doc_hxtorch_mac  =R"doc(The bare mutliply-accumulate operation of BrainScaleS-2. A 1D input @p xis multiplied by the weight matrix @p weights. If @p x is two-dimensional,the weights are sent only once to the synapse array and the inputs areconsecutively multiplied as a 1D vector.@param x Input tensor@param weights The weights of the synapse array@param num_sends How often to send the (same) input vector@param wait_between_events How long to wait (in FPGA cycles) between events@param mock Enable mock mode@return Resulting tensor)doc"

static const char * __doc_hxtorch_matmul  =R"doc(Drop-in replacement for the torch.matmul operation that uses BrainScaleS-2.@noteThe current implementation only supports @p other to be 1D or 2D.@param input First input tensor@param other Second input tensor@param num_sends How often to send the (same) input vector@param wait_between_events How long to wait (in FPGA cycles) between events@param mock: Enable mock mode@return Resulting tensor)doc"

static const char * __doc_hxtorch_measure_mock_parameter  =R"doc(Measures the mock parameters, i.e. gain and noise_std, by multiplying afull weight with an artificial test input on the BSS-2 chip.For this purpose a random pattern is used, whose mean value is successivelyreduced to also work with higher gain factors.The output for the actual calibration is chosen such that it is close tothe middle of the available range.)doc"

static const char * __doc_hxtorch_MockParameter   = R"doc(Parameter of hardware mock.)doc"

static const char * __doc_hxtorch_MockParameter_MockParameter  =R"doc(Construct with noise standard deviation and gain.@param noise_std Noise standard deviation to use@param gain Gain to use)doc"

static const char * __doc_hxtorch_release_hardware   = R"doc(Release hardware resource.)doc"

static const char * __doc_hxtorch_relu  =R"doc(Rectified linear unit operating on int8 value range.@param input Input tensor@param mock Enable mock mode)doc"

static const char * __doc_hxtorch_set_mock_parameter   = R"doc(Sets the mock parameters.)doc"

file matmul.h

#include <torch/torch.h>#include “hxtorch/constants.h”

file run.h

#include “grenade/vx/execution_instance_playback_hooks.h”#include “grenade/vx/io_data_map.h”#include “grenade/vx/network/network_graph.h”#include “lola/vx/v3/chip.h”

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch/include/hxtorch/detail

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch/include/hxtorch

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch/include

dir /jenkins/jenlib_workspaces_f9/doc_gerrit_documentation-brainscales2.ZG9jX2dlcnJpdF9kb2N1bWVudGF0aW9uLWJyYWluc2NhbGVzMiMzNzk.x/hxtorch/include/hxtorch/snn