pyrsess API documentation

# pyrsess

Python distribution matcher module implemented in Rust.

View Source

    1from .pyrsess import *
    2
    3__doc__ = pyrsess.__doc__
    4if hasattr(pyrsess, "__all__"):
    5    __all__ = pyrsess.__all__

class ESS:

Encoder / decoder using the enumerative sphere shaping algorithm

The implementation follows https://doi.org/10.1109/TWC.2019.2951139.

ESS(e_max: int, n_max: int, ask: int)
def n_max(self) -> int:

Returns the number of amplitudes in an amplitude sequence

def e_max(self) -> int:

Returns the maximum allowed energy for an amplitude sequence

def ask_num(self) -> int:

Returns the number of the used ASK, e.g. 8 if 8-ASK is used

def encode( self, index_bits: Union[numpy.__array_like._SupportsArray[numpy.dtype[Any]], numpy.__nested_sequence._NestedSequence[numpy.__array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy.__nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.uint64]]:

Returns the amplitude sequence for the given bits as a numpy array

The values in `index_bits` should be either `1` or `0`. (Currently other values are possible but this may change.)

This function raises an exception if `index_bits` is invalid.

Args: `index_bits` - numpy array or list

def multi_encode( self, multi_index_bits: Union[numpy.__array_like._SupportsArray[numpy.dtype[Any]], numpy.__nested_sequence._NestedSequence[numpy.__array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy.__nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.uint64]]:

Returns the amplitude sequences for multiple given bit strings as a 2D numpy array

The values in `multi_index_bits` should be either `1` or `0`.

This function raises an exception if one of the index bit strings in `multi_index_bits` is invalid.

Args: `index_bits` - 2D numpy array

def decode( self, sequence: Union[numpy.__array_like._SupportsArray[numpy.dtype[Any]], numpy.__nested_sequence._NestedSequence[numpy.__array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy.__nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.uint64]]:

Returns the index corresponding to the provided amplitude sequence as a numpy array of `1`s and `0`s

Raises an exception if `sequence` is invalid.

Args: `sequence` - numpy array or list

def multi_decode( self, sequences: Union[numpy.__array_like._SupportsArray[numpy.dtype[Any]], numpy.__nested_sequence._NestedSequence[numpy.__array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy.__nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.uint64]]:

Returns the indexes corresponding to the provided amplitude sequence as a 2D numpy array of `1`s and `0`s

Raises an exception if any amplitude sequence in `sequences` is invalid.

Args: `sequences` - 2D numpy array

def num_data_bits(self) -> int:

Returns the number of bits encoded per amplitude sequence

def amplitude_distribution(self) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.float32]]:

Returns the probabilities of the amplitude values

The probabilities are returned as an array with the lowest index corresponding to the lowest amplitude.

def energy_distribution(self) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.float32]]:

Returns the probabilities of the amplitude sequence energies

The probabilities are returned as an array. The corresponding energy values can be calculated with `n_max + 8i` (`n_max` is the number of amplitudes per sequence and `i` is the index in the returned array).

def average_energy(self) -> float:

Returns the average energy of amplitude sequences

def num_sequences(self) -> str:

Returns the number of used amplitude sequences as a string

This will always be a power of two to have a fixed number of bits per amplitude sequence.

def num_sequences_possible(self) -> str:

Returns the maximum number of possible amplitude sequences as a string

WARNING: Effect of limiting the used indexes to a power of two is not regarded!!! If it should be, use `num_sequences` instead.

class OESS:

Encoder / decoder using the optimum enumerative sphere shaping algorithm

Unlike ESS, OESS needs its `e_max` parameter to be 'optimal'. This is the case, if there is no lower `e_max` parameter which leads to a shaper capable of encoding the same number of bits. An optimal `e_max` parameter can be found using `OESS.optimal_e_max()`.

The implementation follows https://doi.org/10.1109/JLT.2022.3201901.

OESS(e_max: int, n_max: int, ask: int)
def optimal_e_max(e_max: int, n_max: int, ask_num: int):

Returns the next lower optimal `e_max` value

An ESS encoder with the provided arguments can encode a certain number of bits. This function returns the lowest `e_max` parameter so that an ESS encoder with the new `e_max` stil encodes the same number of bits.

def n_max(self) -> int:

Returns the number of amplitudes in an amplitude sequence

def e_max(self) -> int:

Returns the maximum allowed energy for an amplitude sequence

def ask_num(self) -> int:

Returns the number of the used ASK, e.g. 8 if 8-ASK is used

def encode( self, index_bits: Union[numpy.__array_like._SupportsArray[numpy.dtype[Any]], numpy.__nested_sequence._NestedSequence[numpy.__array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy.__nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.uint64]]:

Returns the amplitude sequence for the given bits as a numpy array

The values in `index_bits` should be either `1` or `0`. (Currently other values are possible but this may change.)

This function raises an exception if `index_bits` is invalid.

Args: `index_bits` - numpy array or list

def multi_encode( self, multi_index_bits: Union[numpy.__array_like._SupportsArray[numpy.dtype[Any]], numpy.__nested_sequence._NestedSequence[numpy.__array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy.__nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.uint64]]:

Returns the amplitude sequences for multiple given bit strings as a 2D numpy array

The values in `multi_index_bits` should be either `1` or `0`.

This function raises an exception if one of the index bit strings in `multi_index_bits` is invalid.

Args: `index_bits` - 2D numpy array

def decode( self, sequence: Union[numpy.__array_like._SupportsArray[numpy.dtype[Any]], numpy.__nested_sequence._NestedSequence[numpy.__array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy.__nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.uint64]]:

Returns the index corresponding to the provided amplitude sequence as a numpy array of `1`s and `0`s

Raises an exception if `sequence` is invalid.

Args: `sequence` - numpy array or list

def multi_decode( self, sequences: Union[numpy.__array_like._SupportsArray[numpy.dtype[Any]], numpy.__nested_sequence._NestedSequence[numpy.__array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy.__nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.uint64]]:

Returns the indexes corresponding to the provided amplitude sequence as a 2D numpy array of `1`s and `0`s

Raises an exception if any amplitude sequence in `sequences` is invalid.

Args: `sequences` - 2D numpy array

def num_data_bits(self) -> int:

Returns the number of bits encoded per amplitude sequence

def amplitude_distribution(self) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.float32]]:

Returns the probabilities of the amplitude values

The probabilities are returned as an array with the lowest index corresponding to the lowest amplitude.

def energy_distribution(self) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.float32]]:

Returns the probabilities of the amplitude sequence energies

The probabilities are returned as an array. The corresponding energy values can be calculated with `n_max + 8i` (`n_max` is the number of amplitudes per sequence and `i` is the index in the returned array).

def average_energy(self) -> float:

Returns the average energy of amplitude sequences

def num_sequences(self) -> str:

Returns the number of used amplitude sequences as a string

This will always be a power of two to have a fixed number of bits per amplitude sequence.

def num_sequences_possible(self) -> str:

Returns the maximum number of possible amplitude sequences as a string

WARNING: Effect of limiting the used indexes to a power of two is not regarded!!! If it should be, use `num_sequences` instead.