asteroid.complex_nn module

Complex building blocks that work with PyTorch native (!) complex tensors, i.e. dtypes complex64/complex128, or tensors for which .is_complex() returns True.

Note that Asteroid code has two other representations of complex numbers:

• Torchaudio representation […, 2] where […, 0] and […, 1] are real and imaginary components, respectively
• Asteroid style representation, identical to the Torchaudio representation, but with the last dimension concatenated: tensor([r1, r2, …, rn, i1, i2, …, in]). The concatenated (2 * n) dimension may be at an arbitrary position, i.e. the tensor is of shape […, 2 * n, …]. See asteroid_filterbanks.transforms for details.

asteroid.complex_nn.is_torch_complex(x)

asteroid.complex_nn.torch_complex_from_magphase(mag, phase)

asteroid.complex_nn.torch_complex_from_reim(re, im)

asteroid.complex_nn.as_torch_complex(x, asteroid_dim: int = -2)

Convert complex x to complex. Input may be one of:

• PyTorch native complex
• Torchaudio style complex
• Asteroid style complex
• Tuple or list of (real, imaginary) components

Parameters:asteroid_dim (int, optional) – Dimension to check for Asteroid-style complex. Raises:ValueError – If type of x is not understood.

asteroid.complex_nn.on_reim(f)

Make a complex-valued function callable from a real-valued one by applying it to the real and imaginary components independently.

Returns:cf(x), complex version of f – A function that applies f to the real and imaginary components of x and returns the result as PyTorch complex tensor.

class asteroid.complex_nn.OnReIm(module_cls, *args, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

Like on_reim, but for stateful modules.

Parameters:module_cls (callable) – A class or function that returns a Torch module/functional. Called 2x with *args, **kwargs, to construct the real and imaginary component modules.

forward(x)

class asteroid.complex_nn.ComplexMultiplicationWrapper(module_cls, *args, **kwargs)

Bases: sphinx.ext.autodoc.importer._MockObject

Make a complex-valued module F from a real-valued module f by applying complex multiplication rules:

F(a + i b) = f1(a) - f1(b) + i (f2(b) + f2(a))

where f1, f2 are instances of f that do not share weights.

Parameters:module_cls (callable) – A class or function that returns a Torch module/functional. Constructor of f in the formula above. Called 2x with *args, **kwargs, to construct the real and imaginary component modules.

forward(x: <sphinx.ext.autodoc.importer._MockObject object at 0x7f85c9a0b490>) → <sphinx.ext.autodoc.importer._MockObject object at 0x7f85c9a0b490>

class asteroid.complex_nn.ComplexSingleRNN(rnn_type, input_size, hidden_size, n_layers=1, dropout=0, bidirectional=False)

Bases: sphinx.ext.autodoc.importer._MockObject

Module for a complex RNN block.

This is similar to :cls:`asteroid.masknn.recurrent.SingleRNN` but uses complex multiplication as described in [1]. Arguments are identical to those of SingleRNN, except for dropout, which is not yet supported.

Parameters:

• rnn_type (str) – Select from 'RNN', 'LSTM', 'GRU'. Can also be passed in lowercase letters.
• input_size (int) – Dimension of the input feature. The input should have shape [batch, seq_len, input_size].
• hidden_size (int) – Dimension of the hidden state.
• n_layers (int, optional) – Number of layers used in RNN. Default is 1.
• bidirectional (bool, optional) – Whether the RNN layers are bidirectional. Default is False.
• dropout – Not yet supported.

References

[1] : “DCCRN: Deep Complex Convolution Recurrent Network for Phase-Aware Speech Enhancement”, Yanxin Hu et al. https://arxiv.org/abs/2008.00264

output_size

forward(x: <sphinx.ext.autodoc.importer._MockObject object at 0x7f85c9a0b490>) → <sphinx.ext.autodoc.importer._MockObject object at 0x7f85c9a0b490>

Input shape [batch, seq, feats]

class asteroid.complex_nn.BoundComplexMask(bound_type)

Bases: sphinx.ext.autodoc.importer._MockObject

Module version of bound_complex_mask

forward(mask: <sphinx.ext.autodoc.importer._MockObject object at 0x7f85c9a0b490>)

asteroid.complex_nn.bound_complex_mask(mask: <sphinx.ext.autodoc.importer._MockObject object at 0x7f85c9a0b490>, bound_type='tanh')

Bound a complex mask, as proposed in [1], section 3.2.

Valid bound types, for a complex mask \(M = |M| ⋅ e^{i φ(M)}\):

• Unbounded (“UBD”): \(M_{\mathrm{UBD}} = M\)
• Sigmoid (“BDSS”): \(M_{\mathrm{BDSS}} = σ(|M|) e^{i σ(φ(M))}\)
• Tanh (“BDT”): \(M_{\mathrm{BDT}} = \mathrm{tanh}(|M|) e^{i φ(M)}\)

Parameters:bound_type (str or None) – The type of bound to use, either of “tanh”/”bdt” (default), “sigmoid”/”bdss” or None/”bdt”.

References

[1] : “Phase-aware Speech Enhancement with Deep Complex U-Net”, Hyeong-Seok Choi et al. https://arxiv.org/abs/1903.03107