neurophox.tensorflow package

neurophox.tensorflow.generic module

class neurophox.tensorflow.generic.CompoundTransformerLayer(units, transformer_list)

Bases: neurophox.tensorflow.generic.TransformerLayer

Compound transformer class for unitary matrices

Parameters

• units (int) – Dimension of the input to be transformed by the transformer

• transformer_list (List[TransformerLayer]) – List of Transformer objects to apply to the inputs

• is_complex – Whether the input to be transformed is complex

inverse_transform(outputs)

Outputs are inverse-transformed by \(L\) transformer layers \(T^{(\ell)} \in \mathbb{C}^{N \times N}\) as follows:

\[V_{\mathrm{in}} = V_{\mathrm{out}} \prod_{\ell=L}^1 T_\ell^{-1},\]

where \(V_{\mathrm{out}}, V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\).

Parameters

outputs (Tensor) – Output batch represented by the matrix \(V_{\mathrm{out}} \in \mathbb{C}^{M \times N}\)

Return type

Tensor

Returns

Transformed outputs, \(V_{\mathrm{in}}\)

transform(inputs)

Inputs are transformed by \(L\) transformer layers \(T^{(\ell)} \in \mathbb{C}^{N \times N}\) as follows:

\[V_{\mathrm{out}} = V_{\mathrm{in}} \prod_{\ell=1}^L T_\ell,\]

where \(V_{\mathrm{out}}, V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\).

Parameters

inputs (Tensor) – Input batch represented by the matrix \(V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\)

Return type

Tensor

Returns

Transformed inputs, \(V_{\mathrm{out}}\)

class neurophox.tensorflow.generic.Mesh(model)

Bases: object

mesh_layers(phases)

Parameters

phases (MeshPhasesTensorflow) – The MeshPhasesTensorflow object containing \(\boldsymbol{\theta}, \boldsymbol{\phi}, \boldsymbol{\gamma}\)

Return type

List[MeshVerticalLayer]

Returns

List of mesh layers to be used by any instance of MeshLayer

class neurophox.tensorflow.generic.MeshLayer(mesh_model, activation=None, incoherent=False, phase_loss_fn=None, **kwargs)

Bases: neurophox.tensorflow.generic.TransformerLayer

Mesh network layer for unitary operators implemented in numpy

Parameters

• mesh_model (MeshModel) – The MeshModel model of the mesh network (e.g., rectangular, triangular, custom, etc.)

• activation (Optional[Activation]) – Nonlinear activation function (None if there’s no nonlinearity)

• incoherent (bool) – Use an incoherent representation for the layer (no phase coherent between respective inputs…)

• phases – Initialize with phases (overrides mesh model initialization)

inverse_transform(outputs: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor

Performs the operation (where \(U\) represents the matrix for this layer):

\[V_{\mathrm{in}} = V_{\mathrm{out}} U^\dagger,\]

where \(U \in \mathrm{U}(N)\) and \(V_{\mathrm{out}}, V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\).

Parameters

outputs (Tensor) – outputs batch represented by the matrix \(V_{\mathrm{out}} \in \mathbb{C}^{M \times N}\)

Return type

Tensor

Returns

Inverse transformed outputs, \(V_{\mathrm{in}}\)

property phases

Returns: The MeshPhases object for this layer

Return type

MeshPhases

property phases_and_layers

Returns: Phases and layers for this mesh layer

Return type

Tuple[MeshPhasesTensorflow, List[MeshVerticalLayer]]

transform(inputs: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor

Performs the operation (where \(U\) represents the matrix for this layer):

\[V_{\mathrm{out}} = V_{\mathrm{in}} U,\]

where \(U \in \mathrm{U}(N)\) and \(V_{\mathrm{out}}, V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\).

Parameters

inputs (Tensor) – inputs batch represented by the matrix \(V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\)

Return type

Tensor

Returns

Transformed inputs, \(V_{\mathrm{out}}\)

class neurophox.tensorflow.generic.MeshParamTensorflow(param, units)

Bases: object

A class that cleanly arranges parameters into a specific arrangement that can be used to simulate any mesh

Parameters

• param (Tensor) – parameter to arrange in mesh

• units (int) – number of inputs/outputs of the mesh

property common_mode_arrangement

The common-mode arrangement based on the \(C(\theta)\) transfer matrix for PhaseShiftCommonMode is one where elements of param are on the even rows and repeated on respective odd rows.

In particular, given the param array \(\boldsymbol{\theta} = [\boldsymbol{\theta}_1, \boldsymbol{\theta}_2, \ldots \boldsymbol{\theta}_M]^T\), where \(\boldsymbol{\theta}_n\) represent row vectors and \(M = \lfloor\frac{N}{2}\rfloor\), the common-mode arrangement has the stripe array form \(\widetilde{\boldsymbol{\theta}} = [\boldsymbol{\theta}_1, \boldsymbol{\theta}_1,\boldsymbol{\theta}_2, \boldsymbol{\theta}_2, \ldots \boldsymbol{\theta}_N, \boldsymbol{\theta}_N]^T\). where \(\widetilde{\boldsymbol{\theta}} \in \mathbb{R}^{N \times L}\) defines the \(\boldsymbol{\theta}\) of the final mesh.

Return type

Tensor

Returns

Common-mode arrangement array of phases

property differential_mode_arrangement

The differential-mode arrangement is based on the \(D(\theta)\) transfer matrix for PhaseShiftDifferentialMode.

Given the param array \(\boldsymbol{\theta} = [\cdots \boldsymbol{\theta}_m \cdots]^T\), where \(\boldsymbol{\theta}_n\) represent row vectors and \(M = \lfloor\frac{N}{2}\rfloor\), the differential-mode arrangement has the form \(\widetilde{\boldsymbol{\theta}} = \left[\cdots \frac{\boldsymbol{\theta}_m}{2}, -\frac{\boldsymbol{\theta}_m}{2} \cdots \right]^T\). where \(\widetilde{\boldsymbol{\theta}} \in \mathbb{R}^{N \times L}\) defines the \(\boldsymbol{\theta}\) of the final mesh.

Return type

Tensor

Returns

Differential-mode arrangement array of phases

property single_mode_arrangement

The single-mode arrangement based on the \(L(\theta)\) transfer matrix for PhaseShiftUpper is one where elements of param are on the even rows and all odd rows are zero.

In particular, given the param array \(\boldsymbol{\theta} = [\boldsymbol{\theta}_1, \boldsymbol{\theta}_2, \ldots \boldsymbol{\theta}_M]^T\), where \(\boldsymbol{\theta}_m\) represent row vectors and \(M = \lfloor\frac{N}{2}\rfloor\), the single-mode arrangement has the stripe array form \(\widetilde{\boldsymbol{\theta}} = [\boldsymbol{\theta}_1, \boldsymbol{0}, \boldsymbol{\theta}_2, \boldsymbol{0}, \ldots \boldsymbol{\theta}_N, \boldsymbol{0}]^T\). where \(\widetilde{\boldsymbol{\theta}} \in \mathbb{R}^{N \times L}\) defines the \(\boldsymbol{\theta}\) of the final mesh and \(\boldsymbol{0}\) represents an array of zeros of the same size as \(\boldsymbol{\theta}_n\).

Returns

Single-mode arrangement array of phases

class neurophox.tensorflow.generic.MeshPhasesTensorflow(theta, phi, mask, gamma, units, basis='sm', hadamard=False, theta_fn=None, phi_fn=None, gamma_fn=None, phase_loss_fn=None)

Bases: object

Organizes the phases in the mesh into appropriate arrangements

Parameters

• theta (Variable) – Array to be converted to \(\boldsymbol{\theta}\)

• phi (Variable) – Array to be converted to \(\boldsymbol{\phi}\)

• gamma (Variable) – Array to be converted to \(\boldsymbol{\gamma}\)

• mask (ndarray) – Mask over values of theta and phi that are not in bar state

• basis (str) – Phase basis to use

• hadamard (bool) – Whether to use Hadamard convention

• theta_fn (Optional[Callable]) – TF-friendly phi function call to reparametrize phi (example use cases: see neurophox.helpers). By default, use identity function.

• phi_fn (Optional[Callable]) – TF-friendly phi function call to reparametrize phi (example use cases: see neurophox.helpers). By default, use identity function.

• gamma_fn (Optional[Callable]) – TF-friendly gamma function call to reparametrize gamma (example use cases: see neurophox.helpers).

• phase_loss_fn (Optional[Callable[[Tensor], Tensor]]) – Incorporate phase shift-dependent loss into the model. The function is of the form phase_loss_fn(phases), which returns the loss

property external_phase_shift_layers

Elementwise applying complex exponential to external_phase_shifts.

Returns

External phase shift layers corresponding to \(\boldsymbol{\phi}\)

property external_phase_shifts

The external phase shift matrix of the mesh corresponds to an L times N array of phase shifts (outside of beamsplitters, thus external) where \(L\) is number of layers and \(N\) is number of inputs/outputs

Returns

External phase shift matrix corresponding to \(\boldsymbol{\phi}\)

property internal_phase_shift_layers

Elementwise applying complex exponential to internal_phase_shifts.

Returns

Internal phase shift layers corresponding to \(\boldsymbol{\theta}\)

property internal_phase_shifts

The internal phase shift matrix of the mesh corresponds to an L times N array of phase shifts (in between beamsplitters, thus internal) where \(L\) is number of layers and \(N\) is number of inputs/outputs

Returns

Internal phase shift matrix corresponding to \(\boldsymbol{\theta}\)

class neurophox.tensorflow.generic.MeshVerticalLayer(pairwise_perm_idx, diag, off_diag, right_perm=None, left_perm=None)

Bases: neurophox.tensorflow.generic.TransformerLayer

Parameters

• diag (Tensor) – the diagonal terms to multiply

• off_diag (Tensor) – the off-diagonal terms to multiply

• left_perm (Optional[PermutationLayer]) – the permutation for the mesh vertical layer (prior to the coupling operation)

• right_perm (Optional[PermutationLayer]) – the right permutation for the mesh vertical layer (usually for the final layer and after the coupling operation)

inverse_transform(outputs)

Inverse-propagate inputs through single layer \(\ell < L\) (where \(U_\ell\) represents the matrix for layer \(\ell\)):

\[V_{\mathrm{in}} = V_{\mathrm{out}} (U^{(\ell')})^\dagger,\]

Parameters

outputs (Tensor) – outputs batch represented by the matrix \(V_{\mathrm{out}} \in \mathbb{C}^{M \times N}\)

Returns

Inverse propaged outputs through single layer \(\ell\) to form an array \(V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\).

transform(inputs)

Propagate inputs through single layer \(\ell < L\) (where \(U_\ell\) represents the matrix for layer \(\ell\)):

\[V_{\mathrm{out}} = V_{\mathrm{in}} U^{(\ell')},\]

Parameters

inputs (Tensor) – inputs batch represented by the matrix \(V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\)

Returns

Propaged inputs through single layer \(\ell\) to form an array \(V_{\mathrm{out}} \in \mathbb{C}^{M \times N}\).

class neurophox.tensorflow.generic.PermutationLayer(permuted_indices)

Bases: neurophox.tensorflow.generic.TransformerLayer

Permutation layer

Parameters

permuted_indices (ndarray) – order of indices for the permutation matrix (efficient permutation representation)

inverse_transform(outputs)

Performs the inverse permutation for this layer represented by \(P^{-1}\) defined by inv_permuted_indices:

\[V_{\mathrm{in}} = V_{\mathrm{out}} P^{-1},\]

where \(P\) is any \(N\)-dimensional permutation and \(V_{\mathrm{out}}, V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\).

Parameters

outputs (Tensor) – outputs batch represented by the matrix \(V_{\mathrm{out}} \in \mathbb{C}^{M \times N}\)

Returns

Permuted outputs, \(V_{\mathrm{in}}\)

transform(inputs)

Performs the permutation for this layer represented by \(P\) defined by permuted_indices:

\[V_{\mathrm{out}} = V_{\mathrm{in}} P,\]

where \(P\) is any \(N\)-dimensional permutation and \(V_{\mathrm{out}}, V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\).

Parameters

inputs (Tensor) – Input batch represented by the matrix \(V_{\mathrm{in}} \in \mathbb{C}^{M \times N}\)

Returns

Permuted inputs, \(V_{\mathrm{out}}\)

class neurophox.tensorflow.generic.TransformerLayer(units, activation=None, **kwargs)

Bases: tensorflow.python.keras.engine.base_layer.Layer

Base transformer class for transformer layers (invertible functions, usually linear)

Parameters

• units (int) – Dimension of the input to be transformed by the transformer

• activation (Optional[Activation]) – Nonlinear activation function (None if there’s no nonlinearity)

call(inputs, training=None, mask=None)

This is where the layer’s logic lives.

Parameters

• inputs – Input tensor, or list/tuple of input tensors.

• **kwargs – Additional keyword arguments.

Returns

A tensor or list/tuple of tensors.

property inverse_matrix

Shortcut of transformer.inverse_transform(np.eye(self.units))

Returns

Inverse matrix implemented by layer

inverse_transform(outputs)

Transform outputs using layer

Parameters

outputs (Tensor) – Outputs to be inverse-transformed by layer

Return type

Tensor

Returns

Transformed outputs

property matrix

Shortcut of transformer.transform(np.eye(self.units))

Returns

Matrix implemented by layer

plot(plt)

Plot transformer.matrix.

Parameters

plt – matplotlib.pyplot for plotting

transform(inputs)

Transform inputs using layer (needs to be overwritten by child classes)

Parameters

inputs (Tensor) – Inputs to be transformed by layer

Return type

Tensor

Returns

Transformed inputs

neurophox.tensorflow.layers module

class neurophox.tensorflow.layers.BM(num_layers, hadamard=False, incoherent=False, basis='bloch', bs_error=0.0, theta_init='random_theta', phi_init='random_phi', phase_loss_fn=None, activation=None, **kwargs)

Bases: neurophox.tensorflow.generic.MeshLayer

Butterfly mesh unitary layer

Parameters

• units – The dimension of the unitary matrix (\(N\))

• hadamard (bool) – Hadamard convention for the beamsplitters

• basis (str) – Phase basis to use

• bs_error (float) – Beamsplitter split ratio error

• theta_init (Union[str, tuple, ndarray]) – Initializer for theta (\(\boldsymbol{\theta}\) or \(\theta_{n\ell}\))

• phi_init (Union[str, tuple, ndarray]) – Initializer for phi (\(\boldsymbol{\phi}\) or \(\phi_{n\ell}\))

• phase_loss_fn (Optional[Callable[[Tensor], Tensor]]) – Phase loss function for the layer

• activation (Optional[Activation]) – Nonlinear activation function (None if there’s no nonlinearity)

class neurophox.tensorflow.layers.ButterflyPerm(units, frequency)

Bases: neurophox.tensorflow.generic.PermutationLayer

Butterfly (FFT) permutation layer

The butterfly or FFT permutation for a frequency \(f\) corresponds to switching all inputs that are \(f\) inputs apart. This works most cleanly in a butterfly mesh architecture where the number of inputs, \(N\), and the frequencies, \(f\) are powers of two.

Parameters

• units (int) – Dimension of the input (number of input waveguide ports), \(N\)

• frequency (int) – Frequency of interacting mesh wires (waveguides)

class neurophox.tensorflow.layers.Diagonal(units, is_complex=True, output_units=None, pos=False, **kwargs)

Bases: neurophox.tensorflow.generic.TransformerLayer

Diagonal matrix of gains and losses (not necessarily real)

Parameters

• units (int) – Dimension of the input (number of input waveguide ports), \(N\)

• is_complex (bool) – Whether to use complex values or not

• output_units (Optional[int]) – Dimension of the output (number of output waveguide ports), \(M\). If \(M < N\), remove last \(N - M\) elements. If \(M > N\), pad with \(M - N\) zeros.

• pos (bool) – Enforce positive definite matrix (only positive singular values)

inverse_transform(outputs: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor

Return type

Tensor

transform(inputs: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor

Return type

Tensor

class neurophox.tensorflow.layers.DiagonalPhaseLayer(units, **kwargs)

Bases: neurophox.tensorflow.generic.TransformerLayer

Diagonal matrix of phase shifts

Parameters

units (int) – Dimension of the input (number of input waveguide ports), \(N\)

inverse_transform(outputs: tensorflow.python.framework.ops.Tensor)

transform(inputs: tensorflow.python.framework.ops.Tensor)

class neurophox.tensorflow.layers.PRM(units, tunable_layers_per_block=None, num_tunable_layers_list=None, sampling_frequencies=None, bs_error=0.0, hadamard=False, incoherent=False, theta_init='haar_prm', phi_init='random_phi', gamma_init='random_gamma', phase_loss_fn=None, activation=None, **kwargs)

Bases: neurophox.tensorflow.generic.MeshLayer

Permuting rectangular mesh unitary layer

Parameters

• units (int) – The dimension of the unitary matrix (\(N\)) to be modeled by this transformer

• tunable_layers_per_block (Optional[int]) – The number of tunable layers per block (overrides num_tunable_layers_list, sampling_frequencies)

• num_tunable_layers_list (Optional[List[int]]) – Number of tunable layers in each block in order from left to right

• sampling_frequencies (Optional[List[int]]) – Frequencies of sampling frequencies between the tunable layers

• is_trainable – Whether the parameters are trainable

• bs_error (float) – Photonic error in the beamsplitter

• theta_init (Union[str, tuple, ndarray]) – Initializer for theta (\(\boldsymbol{\theta}\) or \(\theta_{n\ell}\))

• phi_init (Union[str, tuple, ndarray]) – Initializer for phi (\(\boldsymbol{\phi}\) or \(\phi_{n\ell}\))

• gamma_init (Union[str, tuple, ndarray]) – Initializer for gamma (\(\boldsymbol{\gamma}\) or \(\gamma_{n}\))

• phase_loss_fn (Optional[Callable[[Tensor], Tensor]]) – Phase loss function for the layer

• activation (Optional[Activation]) – Nonlinear activation function (None if there’s no nonlinearity)

class neurophox.tensorflow.layers.RM(units, num_layers=None, hadamard=False, incoherent=False, basis='bloch', bs_error=0.0, theta_init='haar_rect', phi_init='random_phi', gamma_init='random_gamma', phase_loss_fn=None, activation=None, **kwargs)

Bases: neurophox.tensorflow.generic.MeshLayer

Rectangular mesh network layer for unitary operators implemented in tensorflow

Parameters

• units (int) – The dimension of the unitary matrix (\(N\))

• num_layers (Optional[int]) – The number of layers (\(L\)) of the mesh

• hadamard (bool) – Hadamard convention for the beamsplitters

• basis (str) – Phase basis to use

• bs_error (float) – Beamsplitter split ratio error

• theta_init (Union[str, tuple, ndarray]) – Initializer for theta (\(\boldsymbol{\theta}\) or \(\theta_{n\ell}\))

• phi_init (Union[str, tuple, ndarray]) – Initializer for phi (\(\boldsymbol{\phi}\) or \(\phi_{n\ell}\))

• gamma_init (Union[str, tuple, ndarray]) – Initializer for gamma (\(\boldsymbol{\gamma}\) or \(\gamma_{n}\))

• phase_loss_fn (Optional[Callable[[Tensor], Tensor]]) – Phase loss function for the layer

• activation (Optional[Activation]) – Nonlinear activation function (None if there’s no nonlinearity)

class neurophox.tensorflow.layers.RectangularPerm(units, frequency)

Bases: neurophox.tensorflow.generic.PermutationLayer

Rectangular permutation layer

The rectangular permutation layer for a frequency \(f\) corresponds effectively is equivalent to adding \(f\) layers of cross state MZIs in a grid configuration to the existing mesh.

Parameters

• units (int) – Dimension of the input (number of input waveguide ports), \(N\)

• frequency (int) – Frequency of interacting mesh wires (waveguides)

class neurophox.tensorflow.layers.SVD(units, mesh_dict, output_units=None, pos_singular_values=False, activation=None)

Bases: neurophox.tensorflow.generic.CompoundTransformerLayer

Singular value decomposition transformer for implementing a matrix.

Notes

SVD requires you specify the unitary transformers used to implement the SVD in unitary_transformer_dict, specifying transformer name and arguments for that transformer.

Parameters

• units (int) – The number of inputs (\(M\)) of the \(M \times N\) matrix to be modelled by the SVD

• mesh_dict (Dict) – The name and properties of the mesh layer used for the SVD

• output_units (Optional[int]) – The dimension of the output (\(N\)) of the \(M \times N\) matrix to be modelled by the SVD

• pos_singular_values (bool) – Whether to allow only positive singular values

• activation (Optional[Activation]) – Nonlinear activation function (None if there’s no nonlinearity)

class neurophox.tensorflow.layers.TM(units, hadamard=False, incoherent=False, basis='bloch', bs_error=0.0, theta_init='haar_tri', phi_init='random_phi', gamma_init='random_gamma', phase_loss_fn=None, activation=None, **kwargs)

Bases: neurophox.tensorflow.generic.MeshLayer

Triangular mesh network layer for unitary operators implemented in tensorflow

Parameters

• units (int) – The dimension of the unitary matrix (\(N\))

• hadamard (bool) – Hadamard convention for the beamsplitters

• basis (str) – Phase basis to use

• bs_error (float) – Beamsplitter split ratio error

• theta_init (Union[str, tuple, ndarray]) – Initializer for theta (\(\boldsymbol{\theta}\) or \(\theta_{n\ell}\))

• phi_init (Union[str, tuple, ndarray]) – Initializer for phi (\(\boldsymbol{\phi}\) or \(\phi_{n\ell}\))

• gamma_init (Union[str, tuple, ndarray]) – Initializer for gamma (\(\boldsymbol{\gamma}\) or \(\gamma_{n}\))

• phase_loss_fn (Optional[Callable[[Tensor], Tensor]]) – Phase loss function for the layer

• activation (Optional[Activation]) – Nonlinear activation function (None if there’s no nonlinearity)