BigARTM command line utilityΒΆ

This document provides an overview of cpp_client, a simple command-line utility shipped with BigARTM.

To run cpp_client you need to download input data (a textual collection represented in bag-of-words format). We recommend to download vocab and docword files by links provided in Parse collection section of the tutorial. Then you can use cpp_client as follows:

cpp_client -d docword.kos.txt -v vocab.kos.txt

You may append the following options to customize the resulting topic model:

  • -t or --num_topic sets the number of topics in the resulting topic model.
  • -i or --num_iters sets the number of iterative scans over the collection.
  • --num_inner_iters sets the number of updates of theta matrix performed on each iteration.
  • --reuse_theta enables caching of Theta matrix and re-uses last Theta matrix from the previous iteration as initial approximation on the next iteration. The default alternative without --reuse_theta switch is to generate random approximation of Theta matrix on each iteration.
  • --tau_phi, --tau_theta and --tau_decor allows you to specify weights of different regularizers. Currently cpp_client does not allow you to customize regularizer weights for different topics and for different iterations. This limitation is only related to cpp_client, and you can simply achieve this by using BigARTM interface (either in Python or in C++).
  • --online_decay and --online_period are the parameters of online algorithm. online_period specifies time interval in milliseconds between model synchronization. Once per this time interval the topic model will be re-calculated as follows: n_wt counters in the old model are decreased according to online_decay coefficient, and increased by n_wt counters calculated by all processors since the last model synchronization. The suggested way to choose online_period is to measure single iteration time for cpp_client in offline mode (e.g. without online_period option). Then set online_period to lambda = 0.25 of the iteration time. For larger collections it may be more efficient to set online_period to lambda = 0.1 of the iteration time, but then remember to update online_decay parameter accordingly (1-lambda should be a reasonable value).

You may also apply the following optimizations that should not change the resulting model

  • --reuse_batches skips parsing of docword and vocab files, and tries to use batches located in --batch_folder. You may download pre-parsed batches by links provided in Parse collection section of the tutorial.
  • -p allows you to specify number of concurrent processors. The recommended value is to use the number of logical cores on your machine.
  • --no_scores disables calculation and visualization of all scores. This is a clean way of measuring pure performance of BigARTM, because at the moment some scores takes unnecessary long time to calculate.
  • --disk_cache_folder applies only together with --reuse_theta. This parameter allows you to specify a writable disk location where BigARTM can cache Theta matrix between iterations to avoid storing it in main memory.
>cpp_client --help
BigARTM - library for advanced topic modeling (

Basic options:
  -h [ --help ]                         display this help message
  -d [ --docword ] arg                  docword file in UCI format
  -v [ --vocab ] arg                    vocab file in UCI format
  -t [ --num_topic ] arg (=16)          number of topics
  -p [ --num_processors ] arg (=2)      number of concurrent processors
  -i [ --num_iters ] arg (=10)          number of outer iterations
  --num_inner_iters arg (=10)           number of inner iterations
  --reuse_theta                         reuse theta between iterations
  --batch_folder arg (=batches)         temporary folder to store batches
  --dictionary_file arg (=filename of dictionary file)
  --reuse_batches                       reuse batches found in batch_folder
                                        (default = false)
  --items_per_batch arg (=500)          number of items per batch
  --tau_phi arg (=0)                    regularization coefficient for PHI
  --tau_theta arg (=0)                  regularization coefficient for THETA
  --tau_decor arg (=0)                  regularization coefficient for topics
                                        decorrelation (use with care, since
                                        this value heavily depends on the size
                                        of the dataset)
  --paused                              wait for keystroke (allows to attach a
  --no_scores                           disable calculation of all scores
  --online_period arg (=0)              period in milliseconds between model
                                        synchronization on the online algorithm
  --online_decay arg (=0.75)            decay coefficient [0..1] for online
  --parsing_format arg (=0)             parsing format (0 - UCI, 1 - matrix
  --disk_cache_folder arg               disk cache folder

Networking options (experimental):
  --nodes arg                  endpoints of the remote nodes (enables network
                               modus operandi)
  --localhost arg (=localhost) DNS name or the IP address of the localhost
  --port arg (=5550)           port to use for master node
  --proxy arg                  proxy endpoint
  --timeout arg (=1000)        network communication timeout in milliseconds

        cpp_client -d docword.kos.txt -v vocab.kos.txt
        set GLOG_logtostderr=1 & cpp_client -d docword.kos.txt -v vocab.kos.txt

For further details please refer to the source code of cpp_client.