Public | Automated Build

Last pushed: 2 years ago
Short Description
Automated build from
Full Description


Plda is a parallel C++ implementation of Latent Dirichlet Allocation (LDA) [1,2]. We are expecting to present a highly optimized parallel implemention of the Gibbs sampling algorithm for the training/inference of LDA [3]. The carefully designed architecture is expected to support extensions of this algorithm.

We will release an enhanced parallel implementation of LDA, named as PLDA+ [2], which can improve scalability of LDA by significantly reducing the unparallelizable communication bottleneck and achieve good load balancing.


Parallel lda must be run in linux environment with g++ compiler and mpich installed.

Quick Start

  • Use Docker to simulate parallel environment.

    cd plda/docker

    It will first build the plad image, then create a container as "master" and two other containers named node1 and node2, respectively. After the containers started, the master will start training in node1 and node2.

  • Visualization
    We recommend that you use Weave Scope to monitor Docker containers.
    Please refer to install weave scope.


Install mpich

  • Download the latest mpich here, and install.

Install plda

  • Download and build plda
      git clone 
      cd plda
      make all
  • You will see a binary file lda, mpi_lda and infer generated in the folder
  • We use mpich builtin compiler mpicxx to compile, it is a wrap of g++.

Data Format

  • Data is stored using a sparse representation, with one document per line. Each line is the words of this document together with the word count. The format of the data file is:

    <word1> <word1_count> <word2> <word2_count> <word3> <word3_count> ...
  • Each word is an arbitrary string, but it is not expected to contain space/newline or other special characters.
  • Example: Suppose there are two documents. The first one is "a is a character"; The second one is "b is a character after a". Then the datafile would look like:

    a 2 is 1 character 1
    a 2 is 1 b 1 character 1 after 1



  • Train
    • ./lda --num_topics 2 --alpha 0.1 --beta 0.01 --training_data_file testdata/test_data.txt --model_file /tmp/lda_model.txt --burn_in_iterations 100 --total_iterations 150
  • Train parallelly
    • Prepare data the same as the single processor version.
    • mpiexec -n 5 ./mpi_lda --num_topics 2 --alpha 0.1 --beta 0.01 --training_data_file testdata/test_data.txt --model_file /tmp/lda_model.txt --total_iterations 150
    • The input and output are the same with single processor version.
  • Training flags
    • alpha: Suggested to be 50/number_of_topics
    • beta: Suggested to be 0.01
    • num_topics: The total number of topics.
    • total_iterations: The total number of GibbsSampling iterations.
    • burn_in_iterations: After --burn_in_iterations iteration, the model will be almost converged. Then we will average models of the last (total_iterations-burn_in_iterations) iterations as the final model. This only takes effect for single processor version. For example: you set total_iterations to 200, you found that after 170 iterations, the model is almost converged. Then you could set burn_in_iterations to 170 so that the final model will be the average of the last 30 iterations.
    • model_file: The output file of the trained model.
    • training_data_file: The training data.
  • Trained Model
    • After training completes, you will see a file /tmp/lda_model.txt generated. This file stores the training result. Each line is the topic distribution of a word. The first element is the word string, then its occurrence count within each topic.
    • You could use to convert the model to a readable text.


  • Infer unseen documents:
    • ./infer --alpha 0.1 --beta 0.01 --inference_data_file testdata/test_data.txt --inference_result_file /tmp/inference_result.txt --model_file /tmp/lda_model.txt --total_iterations 15 --burn_in_iterations 10
  • Inferring flags:
    • alpha and beta should be the same with training.
    • total_iterations: The total number of GibbsSampling iterations for an unseen document to determine its word topics. This number needs not be as much as training, usually tens of iterations is enough.
    • burn_in_iterations: For an unseen document, we will average the document_topic_distribution of the last (total_iterations-burn_in_iterations) iterations as the final document_topic_distribution.


Here we provide an simple example using the plda and New York Times news articles to train a topic model.

  • Download data
    We use Bag of Words Data Set created by David Newman, UCI. This data set contains five text collections in the form of bags-of-words. We use the New York Times news articles collection which includes 300000 documents, 102660 words in the vocabulary. The total number of words in this collection is approximately 100,000,000. The stopwords have been removed.

    cd plda/testdata
  • Change the data to the proper format as described above.
    ./ nytimes
    Because the data set is big, this step will take several minutes. It will create an single training data file named "nytimes.txt".

  • Train parallelly
    We ran the example on a mpi-cluster with 8 machines, each with a Intel Xeon CPU E5-1410(2.8GHz) and 16GB of memory.

    mpiexec -n 8 ./mpi_lda --num_topics 10 --alpha 0.1 --beta 0.01 --training_data_file testdata/nytimes.txt --model_file /tmp/ny_model_8.txt --burn_in_iterations 100 --total_iterations 150

    Note: The above executing command can be ran from any of the 8 hosts, but the date set(nytimes.txt) should be copied to the identical location of all the hosts.

  • Training performance
    Also, we ran the same example with different number of machines from 1~8 on the same cluster, and here is the results:

    • Memory:

      1. The memory cost is almost linearly reduced as the number of the machines increase.

      2. During running time, all the documents are distributely stored. If your corpus is huge, you could add more machines.

      3. The memory cost is NUM_VOCABULARY NUM_TOPICS sizeof(int64) bytes, and you have to make sure the sum of all machines' memory must be greater than this. If not, you have to reduce your vocabulary size or reduce num_topics.

    • Speedup:

      1. For each iteration, all computers do GibbsSampling parallelly. At the end of iterations, they reduces updated model. Generally, if the corpus is large and the model is small, the speedup is almost linear. If the model is large and the corpus is small, the speedup may be worse than linear.

      2. The performance may also be infected by the conditions of network/computing resource of the mpi-cluster.

  • View Model
    We can view the trained mobel using to convert the model to a readable text.

    python /tmp/ny_model_8.txt

    And we selete some words from it in each topic as shown in below table:

<th align="center">Topic<br>0</th>
<th align="center">Topic<br>1</th>
<th align="center">Topic<br>2</th>
<th align="center">Topic<br>3</th>
<th align="center">Topic<br>4</th>
<th align="center">Topic<br>5</th>
<th align="center">Topic<br>6</th>
<th align="center">Topic<br>7</th>
<th align="center">Topic<br>8</th>
<th align="center">Topic<br>9</th>
<td align="center">law</td>
<td align="center">president</td>
<td align="center">food</td>
<td align="center">government</td>
<td align="center">patient</td>
<td align="center">com</td>
<td align="center">company</td>
<td align="center">team</td>
<td align="center">show</td>
<td align="center">school</td>
<td align="center">case</td>
<td align="center">election</td>
<td align="center">cup</td>
<td align="center">official</td>
<td align="center">drug</td>
<td align="center">web</td>
<td align="center">million</td>
<td align="center">game</td>
<td align="center">film</td>
<td align="center">student</td>
<td align="center">court</td>
<td align="center">political</td>
<td align="center">water</td>
<td align="center">military</td>
<td align="center">doctor</td>
<td align="center">computer</td>
<td align="center">market</td>
<td align="center">season</td>
<td align="center">movie</td>
<td align="center">children</td>
<th align="center">...</th>
<th align="center">...</th>
<th align="center">...</th>
<th align="center">...</th>
<th align="center">...</th>
<th align="center">...</th>
<th align="center">...</th>
<th align="center">...</th>
<th align="center">...</th>
<th align="center">...</th>


If you wish to publish any work based on plda, please cite our paper as:

Zhiyuan Liu, Yuzhou Zhang, Edward Y. Chang, Maosong Sun, PLDA+: Parallel Latent Dirichlet Allocation with Data Placement and Pipeline Processing. ACM Transactions on Intelligent Systems and Technology, special issue on Large Scale Machine Learning. 2011. Software available at

The bibtex format is:

  author = {Zhiyuan Liu and Yuzhou Zhang and Edward Y. Chang and Maosong Sun},
  title = {PLDA+: Parallel Latent Dirichlet Allocation with Data Placement and Pipeline Processing},
  year = {2011},
  journal = {ACM Transactions on Intelligent Systems and Technology, special issue on Large Scale Machine Learning},
  note = {Software available at \url{}}

If you have any questions, please visit


[1] PLDA+: Parallel Latent Dirichlet Allocation with Data Placement and Pipeline Processing. Zhiyuan Liu, Yuzhou Zhang, Edward Y. Chang, Maosong Sun. ACM Transactions on Intelligent Systems and Technology, special issue on Large Scale Machine Learning. 2011.

[2] PLDA: Parallel Latent Dirichlet Allocation for Large-scale Applications. Yi Wang, Hongjie Bai, Matt Stanton, Wen-Yen Chen, and Edward Y. Chang. AAIM 2009.

[3] Latent Dirichlet Allocation, Blei et al., JMLR (3), 2003.

[4] Finding scientific topics, Griffiths and Steyvers, PNAS (101), 2004.

[5] Fast collapsed gibbs sampling for latent dirichlet allocation, Porteous et al., KDD 2008.

[6] Distributed Inference for Latent Dirichlet Allocation, Newman et al., NIPS 2007.

Papers using plda code:

[7] Collaborative Filtering for Orkut Communities: Discovery of User Latent Behavior. Wen-Yen Chen et al., WWW 2009.

Docker Pull Command
Source Repository