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 1s and 0s

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 1s and 0s

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.