# Options

## atc::Options

struct Options

  This struct defines a series of compression and/or decompression options. Almost all ATC interface functions accept an optional `atc::Options` object. When not given, a new `atc::Options` object will be constructed using the default constructor, initializing all options to their default values shown below.

  Public Members

  bool verbose = false

    If true, ATC will print various status and progress information. If false, warnings will still be printed.

  bool suppress_warnings = false

    If true, ATC will not print warnings anymore.

  bool timings = false

    Tracks the time (normally real-time) taken by various sections of the ATC pipeline. The results are stored in the `timings` field inside `atc::Results`.

  int threads = 0

    The amount of threads that should be used for DCT’s, tensor transpositions, linear algebra as well as quantization and encoding. 0 means ATC will attempt to determine the number of available cores automatically.

  StorageOrder storage_order = StorageOrder::MSI

    Determines the interpretation of mode orders provided by the user and shown to the user, such the the requested ST-HOSVD mode processing order or the order of the displayed sizes when `verbose` is true.

  FloatType float_type = FloatType::float64

    Floating-point type used for data arrays. Single-precision might suffice in certain high error cases, while decreasing execution time and memory usage.

  size_t skip_bytes = 0

    The number of bytes that should be skipped when reading the original data file, e.g. in case there is a header at the start of the file.

  ErrorMetric error_metric = ErrorMetric::PSNR

    The error metric used to express the requested target error and optionally the decompression error calculated by `calculate_error`.

  bool apply_dct = false

    If true, apply an HODCT followed by rank truncation (T-HODCT) before the ST-HOSVD. Theoretically, the T-HODCT might be able to quickly truncate very unimportant (i.e. high-frequency) components from the data, thus speeding up the subsequent ST-HOSVD and quantization steps, while incurring a limited time cost due to its lower complexity. However, in practice we did not find such scenarios, which is why this option is disabled by default.

  double dct_truncation_max_sse_share = 0

    Upper bound to the ratio `sse_introduced_by_dct_truncation`/`sse_introduced_by_rank_truncation`, should be in the interval [0, 1].

  double rank_truncation_max_sse_share = 0.5

    Upper bound to the ratio `sse_introduced_by_rank_truncation`/`target_sse`, should be in the interval [0, 1].

  std::vector<uint8_t> mode_processing_order

    Mode processing order during ST-HOSVD compression. Should be a permutation of `[0, 1, ..., modes - 1]`. If not set, the order is chosen by the compressor using the smallest-mode-first heuristic.

  bool precise_svd = false

    If true, the SVD is calculated using the significantly slower but more precise Eigen::BDCSVD solver instead of using the eigenvalue decomposition of the Gramian matrix. This may have a slight effect on compression in some cases but typically comes with a significant time penalty.

  bool print_squared_singular_values = false

    If true and verbose is true, prints the list of computed squared singular values (or eigenvalues from the Gramian matrix) for each mode during the ST-HOSVD.

  bool householder = true

    If true, compress the factors using their Householder reflector representation before quantization. This can lead to slight compression improvements at the cost of a bit of speed. For more information, see our paper.

  IntType int_type = IntType::uint64

    Internal type used for integer arrays during quantization. This type will be stored in the compressed file and will also be used during decompression. Although 64-bit is the default, 32-bit usually suffices for high to medium compression errors while reducing quantization memory usage, which may also provide minor speed-ups due to improved caching (untested). However, if some ST-HOSVD is applied, peak memory usage will not occur during quantization anyway.

  CoreFlattening core_flattening = CoreFlattening::Unfold

    Determines the core flattening/vectorization method used to convert the core to a one-dimensional array for quantization and encoding. For more information, see our paper.

  std::vector<uint8_t> mode_storage_order

    Mode storage order for core for quantization and encoding purposes. Should be a permutation of `[0, 1, ..., modes - 1]`. For more information, including the default setting, see our paper.

  size_t quantization_blocks = 0

    The number of blocks used to parallellize the quantization process. 0 (default) means that it is set to the number of threads used. For more information, see our paper.

  size_t last_pass_max_threads = 8

    The maximal number of threads that should be used during the last pass of the quantization process. During this pass the SSE reduction is tracked and synchronized in between all threads. To limit this overhead it is best not to use arbitrarily many threads in this step.

  double quantization_rel_error_margin = 0.001

    This parameter determines how precise ATC should try to be when approximating the target error during the quantization phase. For example, when using a target relative error of 2% and a quantization relative error margin of 1%, ATC will try to keep the final error in between 1.99% and 2.01%. However, this is not any kind of guarantee, it’s simply a parameter used to trade increased error control for increased synchronization overhead when parallellizing the quantization phase.

  bool split_bitplane_truncation = true

    If true, ATC will not necessarily encode both leading and trailing bits until the same breakpoint in the last encoded bitplane. This can lead to slight compression improvements at the cost of a bit of speed. For more information, see our paper.

  EntropyCodingMethod entropy_coding_method = EntropyCodingMethod::Arithmetic

    The entropy coding method used for encoding the run-lengths during the quantization and encoding phase.

  std::vector<Slice> cutout

    Determines which section of the original tensor should actually be decompressed. Each slice corresponds to one mode. If `cutout.size()` is smaller than the number of modes, the remaining modes are sliced using the default slicing (start: 0, end: `mode_size` - 1, step: 1). For more information, see the `Slice` class.

  bool autocrop = false

    Crop away first/last rows in factors (i.e. first/last slices in the decompressed tensor) with too little energy. Cannot be used when providing a custom cut-out already.

  double autocrop_threshold = 1e-3

    First/last rows in factors whose root mean square value is smaller than or equal to this value will be cropped away.

  bool calculate_error = false

    If true, a copy of the original data to be kept in memory when loading from a file and after decompression the error of the decompressed data will be calculated and returned using the `error` field in `atc::Results`.

## Enums

enum class atc::StorageOrder

  Represents the interpretation of mode orders provided by the user and shown to the user, such the the requested ST-HOSVD mode processing order.

  Values:

  enumerator MSI

    Most-signficant-index first, also known as C ordering (row-major for matrices)

  enumerator LSI

    Least-signficant-index first, also known as Fortran ordering (column-major for matrices)

enum class atc::FloatType

  Represents the precision of the floating-point type used for internal numerical operations.

  Values:

  enumerator float32

    Single-precision.

  enumerator float64

    Double-precision.

enum class atc::ErrorMetric

  Represents the error metric used. `norm` refers to the Frobenius/Euclidean norm, i.e. the square root of the sum of the squared values, `size` refers to the number of elements in the tensor.

  Values:

  enumerator RelativeError

    `norm(decompressed_data - original_data)/norm(original_data)`

  enumerator RMSE

    `norm(decompressed_data - original_data)/sqrt(size(original_data))`

  enumerator PSNR

    `20*log10((max(original_data) - min(original_data))/RMSE(decompressed_data - original_data))`

enum class atc::IntType

  Represents the size of the integer type used for quantization and encoding.

  Values:

  enumerator uint32

    32-bit

  enumerator uint64

    64-bit

enum class atc::CoreFlattening

  Represents the core flattening/vectorization method used to convert the core to a one-dimensional array for quantization and encoding. For more information, see our paper.

  Values:

  enumerator Unfold

    Also known as lexicographic ordering.

  enumerator Zigzag
  enumerator ZOrder

enum class atc::EntropyCodingMethod

  Represents the entropy coding method used for compressing run-lengths during the encoding process.

  Values:

  enumerator Arithmetic

    Arithmetic coding.

  enumerator ANS

    Asymmetric numeral systems.

## Slicing

class Slice

  This class represents a slicing operation along a single mode. A slice consists of a `start`, `stop` and `step` parameter. For example, the slice `1:10:2` indicates that only the indices `1, 3, 5, 7, 9` should be included. More complex syntax, using undefined implicit parameters and parameters relative to the mode size are also possible. For more information, see NumPy basic slicing and indexing.

  When reducing the original tensor to a more coarse grid (using a `step` parameter greater than 1), you may want to perform this reduction in a smoother way than simply discarding all but 1 out of every `step` slices. To use an alternative linear filter, you can define a set the `reduction` parameter as well. In the string format, this is done by appending the corresponding letter to the slice representation, e.g. `1:10:2b`.

  Public Functions

  Slice(int64_t start = UNDEFINED, int64_t stop = UNDEFINED, int64_t step = UNDEFINED, Reduction reduction = Reduction::Downsampling)

    Create a slice from its raw parameters.

  Slice(const std::string &description)

    Create a slice from its Python description.

  const int64_t &get_start() const

    Returns the `start` parameter.

  const int64_t &get_stop() const

    Returns the `stop` parameter.

  const int64_t &get_step() const

    Returns the `step` parameter.

  const Reduction &get_reduction() const

    Returns the `reduction` parameter.

  Public Static Attributes

  static const int64_t UNDEFINED = std::numeric_limits<int64_t>::min()

    This constant indicates that a `start`/`stop`/`step` value was undefined.

enum class atc::Reduction

  Represents how a tensor grid should be reduced to a coarser grid along one mode. Each of these reductions corresponds to a linear operation, i.e. multiplying the tensor along this mode with a pre-defined matrix.

  Values:

  enumerator Downsampling

    Default reduction, simply takes the value from the index itself and discards the neighboring values.

  enumerator Box

    Averages out all values across an interval of size `step` centered around the index.

  enumerator Lanczos

    Applies Lanczos filtering across an interval of size `2*step` centered around the index.