cnn-text-classification-pytorch: Kim's CNN for sentence classification

Four Python files stand in for Kim's Theano code

Shawn1993/cnn-text-classification-pytorch does one narrow job: it reimplements Kim's Convolutional Neural Networks for Sentence Classification so you can read every line of the model in PyTorch instead of calling a classifier out of a library. The top-level tree holds four Python files, main.py, model.py, mydatasets.py and train.py, next to a README and a .gitignore. No package directory, no test suite, no requirements file, no data folder. That shape suits a reader who wants to follow a sentence from raw string to tensor, and it turns away anyone who wanted something to pip install. Apache-2.0 covers the code, so vendoring it or shipping a modified copy inside a product carries no copyleft obligation. Within the tree, train.py holds the loop, model.py the convolution stack, mydatasets.py the only file that touches MR and SST data, and main.py the argparse surface that produces the help output quoted in the README.

A Dataset and a BucketSampler replace three dead torchtext APIs

The change list records the removal of `torchtext.data.Field`, `BucketIterator` and `Example`, all deprecated APIs, and the README adds that the code no longer depends on `torchtext` or `numpy` at all. What replaced them is standard: a PyTorch `Dataset`, a `DataLoader`, and a custom `BucketSampler` that gets named but never explained. That is a PyTorch 2.0 compatibility patch rather than a modelling change, and the accuracy table is untouched by it. What disappears along with the old APIs is any account of the unglamorous parts: how sentences are tokenised, how the vocabulary is assembled, what a rare or unseen word turns into, and how variable-length sentences reach a convolution that needs equal widths. The README answers none of those questions and mydatasets.py is the only file left to read. Porting a checkpoint trained against the older torchtext code has no documented route either, because nothing maps one vocabulary onto the other.

Every architecture flag moves exactly one knob

The help output is long, and the architecture options inside it are the half worth reading. `-embed-dim N` sets embedding width, 128 by default. `-kernel-num N` sets how many filters of each width are learned, 100 by default, and `-kernel-sizes STR` takes a comma-separated list, 3,4,5 by default, which is what folds Kim's three window sizes into one convolution pass. `-dropout DROPOUT` defaults to 0.5 and `-max-norm FLOAT` defaults to 3.0, an l2 constraint the change list says was added on the fully connected layer to match the original implementation. `-static` freezes the embedding, `-shuffle` reshuffles each epoch, and `-no-phrases` cuts SST from phrase-level to sentence-level training data. `-optimizer OPTIMIZER` takes adam or adadelta and defaults to adam; `-dataset DATASET` takes MR or SST and defaults to MR. Scheduling defaults are equally plain: 256 epochs, batch size 64, a test every 100 steps, a save every 500 steps, and early stopping after 1000 steps without improvement.

One adadelta command reproduces the SST row, not the MR row

Only one of the two reported rows comes with a command:

python3 main.py -dataset SST -embed-dim 300 -batch-size 50 -optimizer adadelta -lr 1.0 -epochs 15 -early-stop 10000 -test-interval 500

Six of its values contradict the defaults, which is the point. SST needs a 300 wide embedding instead of 128, adadelta instead of adam, a learning rate of 1.0 instead of 0.001, batches of 50 instead of 64, 15 epochs instead of 256, and early stopping pushed out to 10000 steps. Leaving `-no-phrases` out keeps phrase-level training data, matching what the results note states about the setup. MR gets no equivalent line anywhere on the page, so its 76.5% against Kim's 76.1% cannot be rebuilt from what is written down. Both rows are CNN-rand, meaning embeddings are learned with the network instead of loaded from pretrained vectors. On the five-class SST task the port reports 45.6% against the paper's 45.0%, and that smaller margin is the honest measure of how much the extra classes cost. A plain training run logs `acc: 59.3750%` on `Batch[100]`, then `57.6923%(615/1066)` on the evaluation pass.

Prediction wants five space-separated tokens and a checkpoint you own

Single-sentence prediction is where the rough edges show. `-predict TEXT` takes the sentence on the command line and `-snapshot FILE` points at a checkpoint, so a working call needs both:

python3 main.py -predict="Hello my dear , I love you so much ." \
                -snapshot="./snapshot/2017-02-11_15-50-53/best_steps1500.pt"

The tree ships no .pt file, and the README says nothing about where a snapshot is meant to live beyond the timestamped path it keeps reusing, ./snapshot/2017-02-11_15-50-53/best_steps1500.pt. That name encodes a save date and a step count, a convention `-save-dir DIR` and `-save-interval N` imply but never define, and `-save-dir DIR` carries no default in the help output at all. Tokenisation is stricter than it looks: your text must be separated by space, punctuation included, and longer than the largest kernel. With the default `-kernel-sizes` of 3,4,5 that means more than five tokens, so a four-word sentence cannot be classified. The README does not say whether a short input raises, truncates or pads. Evaluating an untrained model is equally undefined: the help text describes `-test` as train or test and gives `-snapshot` a default of None, while the prose says that without a snapshot the model starts from scratch.

Two device switches and no documented precedence

Hardware selection has two switches and one documented meaning. `-device DEVICE` takes an index and defaults to -1, which the help text spells out as cpu. `-no-cuda` disables the gpu as a separate flag. Nothing states what happens when both are given, and no example on the page passes either, so every command in the README runs on the CPU. Those defaults matter more here than in most repositories, because the shipped schedule is sized for a GPU: 256 epochs at batch size 64, testing every 100 steps, saving every 500 steps, all on a two-class problem with 1000-step early stopping as the only brake. The change list does record that evaluation and prediction moved inside a `torch.no_grad()` context, so memory is not the bottleneck you should worry about. Wall-clock time is. Anyone reproducing the SST row on a machine without a usable GPU needs to lower `-test-interval N` and `-save-interval N` deliberately rather than inherit them.

No install command, no dataset directory, no checkpoint

The requirement section is two bullets, python >= 3.8 and pytorch >= 2.0, with no pip line, no requirements file in the tree and no environment lock. So the install step is yours: make an environment, install PyTorch at 2.0 or later, clone the repository. Four files with no dependency beyond torch makes that fair, but it hands back work readers expect to be finished. Data is the larger gap. The README states that two datasets were tested, MR with 2 classes and SST with 5, and `-dataset DATASET` accepts either, yet no data directory, no download link and no file format description exist anywhere. If your aim is the 76.5% MR figure, you are writing the loader for mydatasets.py yourself. The last push was on 2026-03-23; every entry in the change list is compatibility work against modern PyTorch, so a newer PyTorch version is unverified.

The Theano, TensorFlow and Keras ports differ only by framework

The introduction names three earlier ports of the same paper: Kim's own Theano implementation, Denny Britz's TensorFlow version and Alexander Rakhlin's Keras version. Their existence sets the bar, and what separates this repository from all three is maintenance rather than mathematics. The change list adds Adadelta, phrase-level SST, an l2 constraint on the fully connected layer, uniform[-0.25, 0.25] embedding initialisation, and the removal of the dead torchtext and numpy-era APIs. Kim's Theano port is the only comparison point in the results table, 76.1% on MR and 45.0% on SST, and both of this port's numbers sit slightly above it. No line on the page measures this code against the TensorFlow or Keras ports on speed, memory or accuracy. None of the three is vendored or installed either, so the choice comes down to the framework you already run.

Editorial conclusion

Adopt this repository when you want to read a whole CNN sentence classifier in one sitting and are willing to write the data loader yourself. Four files, one argparse surface, and flags that map one to one onto Kim's architecture, with Adadelta and phrase-level SST added on top. Leave it alone if you need a packaged classifier, a documented tokeniser, a pretrained checkpoint or a dataset you did not assemble. Before anything else, load your MR or SST files through mydatasets.py, since the README names no file format and ships no data directory.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Shawn1993/cnn-text-classification-pytorch on GitHub