Command-line interface
======================

You can obtain the command-line documentation by executing the CLI executable with the argument ``--help``. For ATC version 1.1.2, this leads to the following output:

.. code-block:: none
   
   ATC version 1.1.2
   
   Usage:
   
   Compression:            ./atc --of <original-file> --type <data-type> --sizes <tensor-sizes> --<error-metric> <target-error> --cf <compressed-file> [OPTIONS]
   Decompression:          ./atc --cf <compressed-file> --df <decompressed-file> [OPTIONS]
   Comp. + decomp.:        ./atc --of <original-file> --type <data-type> --sizes <tensor-sizes> --<error-metric> <target-error> --cf <compressed-file> --df <decompressed-file> [OPTIONS]
   
   Example:                ./atc --of ../data/test_data_3D.raw --type uint8 --sizes 3 3 3 --psnr 80 --cf ../data/comp.atc --df ../data/decomp.raw
   
   Options:
   
   General:
     --help                Produce this help message
     --config arg          Configuration file, storing a set of options and their 
                           values, in the format "<option> = <value>" with each 
                           option on its own line (INI). Boolean options can be 
                           set using e.g. "true". If an option is provided both in
                           the command line and the given configuration file, the 
                           command line will take priority.
     --of arg              Original data file, used as input for compression
     --cf arg              Compressed file, used as output for compression and/or 
                           input for decompression
     --df arg              Decompressed file, used as output for decompression
     --print-results       Print compression/decompression time as well as 
                           compressed file size and compression factor in the case
                           of compression
     --verbose             Print progress/status updates as well as timings in 
                           case --print-results is used
     --suppress            Suppress warnings
     --threads arg         Maximal amount of threads to be used, 0 (default) means
                           that ATC will attempt to use the amount of cores 
                           available on the system.
     --storage-order arg   The ordering of the tensor modes which determines the 
                           tensor flattening. Possible values: msi (default): 
                           most-significant-index first (C order, row-major for 
                           matrices), lsi: least-significant-index first (Fortran 
                           order, column-major for matrices).
     --float-type arg      The floating-point type used for most computational 
                           work internally. Possible values: float32, float64 
                           (default)
   
   Compression:
     --type arg                       Data type of the original file. Possible 
                                      values: uint8, uint16, uint32, uint64, int8,
                                      int16, int32, int64, float32, float64
     --sizes arg                      Sizes of the tensor modes, separated by 
                                      spaces
     --psnr arg                       Target error in terms of PSNR (in dB)
     --re arg                         Target error in terms of relative error
     --rmse arg                       Target error in terms of RMSE
     --skip-bytes arg                 The number of bytes to be skipped in the 
                                      original data file (default: 0)
     --rank-truncation arg            Rank truncation maximal SSE share: upper 
                                      bound to ratio of SSE introduced by rank 
                                      truncation (by default only from the 
                                      ST-HOSVD, optionally also from the T-HODCT) 
                                      to target SSE, should be in the range [0, 1]
                                      (default: 0.5).
     --dct                            Apply T-HODCT preprocessing
     --dct-truncation arg             DCT truncation maximal SSE share: upper 
                                      bound to ratio of SSE introduced in T-HODCT 
                                      to SSE introduced in all rank truncation 
                                      (both in the T-HOSVD and the ST-HOSVD), 
                                      should be in the range [0, 1] (default: 0).
     --mode-processing-order arg      ST-HOSVD mode processing order, specified by
                                      enumerating the mode indices (0-based) in 
                                      the desired order, separated by spaces. 
                                      Default: ST-HOSVD heuristic, smallest modes 
                                      first.
     --precise-svd                    Compute the SVD's using the significantly 
                                      slower but more precise Eigen::BDCSVD solver
                                      instead of using the eigenvalue 
                                      decomposition of the Gramian matrix. 
                                      Disabled by default because this added 
                                      precision normally has no compression effect
                                      in practice.
     --print-sq-sv                    If the verbose flag is set, prints the list 
                                      of computed squared singular values (or 
                                      eigenvalues from the Gramian matrix) for 
                                      each mode during the ST-HOSVD.
     --no-householder                 Disables Householder-reflector-based factor 
                                      compression.
     --int-type arg                   The integer type used for quantization, a 
                                      smaller type can be sufficient for high 
                                      target errors. Possible values: uint32, 
                                      uint64 (default)
     --core-flattening arg            The ordering (permutation) of core 
                                      coefficients that should be used to flatten 
                                      the core for quantization. Possible values: 
                                      unfold (default), zigzag, z-order
     --mode-storage-order arg         The order of the tensor modes in the 
                                      internal representation of the core before 
                                      quantization, can have a significant effect 
                                      on compression efficiency in the case the 
                                      default is core encoding order. Specified by
                                      enumerating the mode indices (0-based) in 
                                      the desired order, separated by spaces. If 
                                      not specified, ATC determines this order 
                                      heuristically.
     --qb arg                         Quantization blocks: the amount of blocks 
                                      the quantized core should be split into in 
                                      order to parallelize quantization and 
                                      dequantization. Default: 0, which means the 
                                      number of blocks will equal the number of 
                                      requested threads.
     --lpmt arg                       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. Default: 8
     --qrem arg                       Sets the quantization relative error margin,
                                      should be a value > 0 and < 1 (default: 
                                      0.001000). Decreasing this value will 
                                      improve error control but slow down 
                                      quantization, especially when the 
                                      last_pass_max_threads parameter is high.
     --no-split-bit-plane-truncation  Disables split bit plane truncation.
     --entropy-coding-method arg      The entropy coding method used to encode the
                                      run-lengths obtained during quantization. 
                                      Possible values: ac (arithmetic coding, 
                                      default), ans (asymmetric numeral systems)
   
   Decompression:
     --cutout arg          Slices (at most one per mode) to be taken from the data
                           during decompression, using NumPy-style notation (e.g. 
                           one slice could be "5:-1:3"), with the individual 
                           slices separated by spaces. If "b" or "l" is appended 
                           to a slice string, respectively box or Lanczos 
                           filtering will be used as the reduction for that slice.
                           For more information check the ATC documentation.
     --autocrop arg        Crop away the first/last slices with too little energy 
                           in the decompressed tensor. The argument is the 
                           autocrop threshold, first/last rows in factors whose 
                           root-mean-squared value is smaller than this value will
                           be removed. This value should be in the range [0, 1].
   
   Compression + decompression (in case --of, --cf and --df are provided):
     --ce                  Calculate and print the actual error of the 
                           decompressed data, using the same error metric as the 
                           target error if specified, otherwise PSNR by default.
