[ { "path": ".github/workflows/checks.yml", "content": "name: checks.yml\n\non: [push, pull_request]\n\njobs:\n build:\n runs-on: ubuntu-latest\n strategy:\n matrix:\n python-version: [3.9]\n steps:\n - uses: actions/checkout@v2\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v2\n with:\n python-version: ${{ matrix.python-version }}\n - name: Install dependencies\n run: |\n sudo apt-get install pandoc\n python -m pip install --upgrade pip\n pip install flake8 \n pip install black\n pip install torch torchtext\n pip install -U pip setuptools wheel\n pip install -U spacy matplotlib seaborn altair jupyterlab jupytext\n if [ -f requirements.txt ]; then pip install -r requirements.txt; fi\n if [ -f requirements.dev.txt ]; then pip install -r requirements.dev.txt; fi\n - name: Lint with flake8\n run: |\n # stop the build if there are Python syntax errors or undefined names\n make flake\n" }, { "path": ".gitignore", "content": "*.ipynb\n.ipynb_checkpoints\n.data\n*.pt\n__pycache__\nwandb\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2018 Alexander Rush\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "Makefile", "content": "notebook: the_annotated_transformer.py\n\tjupytext --to ipynb the_annotated_transformer.py\n\npy: the_annotated_transformer.ipynb\n\tjupytext --to py:percent the_annotated_transformer.ipynb\n\nthe_annotated_transformer.ipynb: the_annotated_transformer.py\n\tjupytext --to ipynb the_annotated_transformer.py\n\nexecute: the_annotated_transformer.py\n\tjupytext --execute --to ipynb the_annotated_transformer.py\n\nhtml: the_annotated_transformer.ipynb\n\tjupytext --execute --to ipynb the_annotated_transformer.py\n\tjupyter nbconvert --to html the_annotated_transformer.ipynb\n\nthe_annotated_transformer.md: the_annotated_transformer.ipynb\n\tjupyter nbconvert --to markdown --execute the_annotated_transformer.ipynb\n\nblog: the_annotated_transformer.md\n\tpandoc docs/header-includes.yaml the_annotated_transformer.md --katex=/usr/local/lib/node_modules/katex/dist/ --output=docs/index.html --to=html5 --css=docs/github.min.css --css=docs/tufte.css --no-highlight --self-contained --metadata pagetitle=\"The Annotated Transformer\" --resource-path=/home/srush/Projects/annotated-transformer/ --indented-code-classes=nohighlight\n\n\n\nflake: the_annotated_transformer.ipynb\n\tflake8 --show-source the_annotated_transformer.py\n\nblack: the_annotated_transformer.ipynb\n\tblack --line-length 79 the_annotated_transformer.py\n\nclean: \n\trm -f the_annotated_transformer.ipynb\n\n# see README.md - IWSLT needs to be downloaded manually to obtain 2016-01.tgz\nmove-dataset:\n\tmkdir -p ~/.torchtext/cache/IWSLT2016\n\tcp 2016-01.tgz ~/.torchtext/cache/IWSLT2016/.\n\nsetup: move-dataset\n\tpip install -r requirements.txt\n" }, { "path": "README.md", "content": "Code for The Annotated Transformer blog post:\n\nhttp://nlp.seas.harvard.edu/annotated-transformer/\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/harvardnlp/annotated-transformer/blob/master/AnnotatedTransformer.ipynb)\n\n![image](https://user-images.githubusercontent.com/35882/166251887-9da909a9-660b-45a9-ae72-0aae89fb38d4.png)\n\n\n\n\n# Package Dependencies\n\nUse `requirements.txt` to install library dependencies with pip:\n\n```\npip install -r requirements.txt\n```\n\n\n# Notebook Setup\n\nThe Annotated Transformer is created using [jupytext](https://github.com/mwouts/jupytext).\n\nRegular notebooks pose problems for source control - cell outputs end up in the repo history and diffs between commits are difficult to examine. Using jupytext, there is a python script (`.py` file) that is automatically kept in sync with the notebook file by the jupytext plugin.\n\nThe python script is committed contains all the cell content and can be used to generate the notebook file. The python script is a regular python source file, markdown sections are included using a standard comment convention, and outputs are not saved. The notebook itself is treated as a build artifact and is not commited to the git repository.\n\nPrior to using this repo, make sure jupytext is installed by following the [installation instructions here](https://github.com/mwouts/jupytext/blob/main/docs/install.md).\n\nTo produce the `.ipynb` notebook file using the markdown source, run (under the hood, the `notebook` build target simply runs `jupytext --to ipynb the_annotated_transformer.py`):\n\n```\nmake notebook\n```\n\nTo produce the html version of the notebook, run:\n\n```\nmake html\n```\n\n`make html` is just a shortcut for for generating the notebook with `jupytext --to ipynb the_annotated_transformer.py` followed by using the jupyter nbconvert command to produce html using `jupyter nbconvert --to html the_annotated_transformer.ipynb` \n \n\n# Formatting and Linting\n\nTo keep the code formatting clean, the annotated transformer git repo has a git action to check that the code conforms to [PEP8 coding standards](https://www.python.org/dev/peps/pep-0008/).\n\nTo make this easier, there are two `Makefile` build targets to run automatic code formatting with black and flake8.\n\nBe sure to [install black](https://github.com/psf/black#installation) and [flake8](https://flake8.pycqa.org/en/latest/).\n\nYou can then run:\n\n```\nmake black\n```\n\n(or alternatively manually call black `black --line-length 79 the_annotated_transformer.py`) to format code automatically using black and:\n\n```\nmake flake\n```\n\n(or manually call flake8 `flake8 --show-source the_annotated_transformer.py) to check for PEP8 violations.\n\nIt's recommended to run these two commands and fix any flake8 errors that arise, when submitting a PR, otherwise the github actions CI will report an error.\n" }, { "path": "docs/header-includes.yaml", "content": "---\nheader-includes: |\n \n \n \n...\n" }, { "path": "docs/index.html", "content": "\n\n\n \n \n \n The Annotated Transformer\n \n \n \n \n \n \n \n \n \n\n\n
\n

\nThe Annotated Transformer\n

\n
\n
\n

\nAttention is All You Need \n

\n
\n

\n\n

The Transformer has been on a lot of people’s minds over the last year five years. This post presents an annotated version of the paper in the form of a line-by-line implementation. It reorders and deletes some sections from the original paper and adds comments throughout. This document itself is a working notebook, and should be a completely usable implementation. Code is available here.

\n

\nTable of Contents\n

\n\n

Prelims

\n

Skip

\n
# !pip install -r requirements.txt
\n
# # Uncomment for colab\n# #\n# !pip install -q torchdata==0.3.0 torchtext==0.12 spacy==3.2 altair GPUtil\n# !python -m spacy download de_core_news_sm\n# !python -m spacy download en_core_web_sm
\n
import os\nfrom os.path import exists\nimport torch\nimport torch.nn as nn\nfrom torch.nn.functional import log_softmax, pad\nimport math\nimport copy\nimport time\nfrom torch.optim.lr_scheduler import LambdaLR\nimport pandas as pd\nimport altair as alt\nfrom torchtext.data.functional import to_map_style_dataset\nfrom torch.utils.data import DataLoader\nfrom torchtext.vocab import build_vocab_from_iterator\nimport torchtext.datasets as datasets\nimport spacy\nimport GPUtil\nimport warnings\nfrom torch.utils.data.distributed import DistributedSampler\nimport torch.distributed as dist\nimport torch.multiprocessing as mp\nfrom torch.nn.parallel import DistributedDataParallel as DDP\n\n\n# Set to False to skip notebook execution (e.g. for debugging)\nwarnings.filterwarnings("ignore")\nRUN_EXAMPLES = True
\n
# Some convenience helper functions used throughout the notebook\n\n\ndef is_interactive_notebook():\n    return __name__ == "__main__"\n\n\ndef show_example(fn, args=[]):\n    if __name__ == "__main__" and RUN_EXAMPLES:\n        return fn(*args)\n\n\ndef execute_example(fn, args=[]):\n    if __name__ == "__main__" and RUN_EXAMPLES:\n        fn(*args)\n\n\nclass DummyOptimizer(torch.optim.Optimizer):\n    def __init__(self):\n        self.param_groups = [{"lr": 0}]\n        None\n\n    def step(self):\n        None\n\n    def zero_grad(self, set_to_none=False):\n        None\n\n\nclass DummyScheduler:\n    def step(self):\n        None
\n
\n

My comments are blockquoted. The main text is all from the paper itself.

\n
\n

Background

\n

The goal of reducing sequential computation also forms the foundation of the Extended Neural GPU, ByteNet and ConvS2S, all of which use convolutional neural networks as basic building block, computing hidden representations in parallel for all input and output positions. In these models, the number of operations required to relate signals from two arbitrary input or output positions grows in the distance between positions, linearly for ConvS2S and logarithmically for ByteNet. This makes it more difficult to learn dependencies between distant positions. In the Transformer this is reduced to a constant number of operations, albeit at the cost of reduced effective resolution due to averaging attention-weighted positions, an effect we counteract with Multi-Head Attention.

\n

Self-attention, sometimes called intra-attention is an attention mechanism relating different positions of a single sequence in order to compute a representation of the sequence. Self-attention has been used successfully in a variety of tasks including reading comprehension, abstractive summarization, textual entailment and learning task-independent sentence representations. End-to-end memory networks are based on a recurrent attention mechanism instead of sequencealigned recurrence and have been shown to perform well on simple-language question answering and language modeling tasks.

\n

To the best of our knowledge, however, the Transformer is the first transduction model relying entirely on self-attention to compute representations of its input and output without using sequence aligned RNNs or convolution.

\n

Part 1: Model Architecture

\n

Model Architecture

\n

Most competitive neural sequence transduction models have an encoder-decoder structure (cite). Here, the encoder maps an input sequence of symbol representations (x_1, ..., x_n) to a sequence of continuous representations \\mathbf{z} = (z_1, ..., z_n). Given \\mathbf{z}, the decoder then generates an output sequence (y_1,...,y_m) of symbols one element at a time. At each step the model is auto-regressive (cite), consuming the previously generated symbols as additional input when generating the next.

\n
class EncoderDecoder(nn.Module):\n    """\n    A standard Encoder-Decoder architecture. Base for this and many\n    other models.\n    """\n\n    def __init__(self, encoder, decoder, src_embed, tgt_embed, generator):\n        super(EncoderDecoder, self).__init__()\n        self.encoder = encoder\n        self.decoder = decoder\n        self.src_embed = src_embed\n        self.tgt_embed = tgt_embed\n        self.generator = generator\n\n    def forward(self, src, tgt, src_mask, tgt_mask):\n        "Take in and process masked src and target sequences."\n        return self.decode(self.encode(src, src_mask), src_mask, tgt, tgt_mask)\n\n    def encode(self, src, src_mask):\n        return self.encoder(self.src_embed(src), src_mask)\n\n    def decode(self, memory, src_mask, tgt, tgt_mask):\n        return self.decoder(self.tgt_embed(tgt), memory, src_mask, tgt_mask)
\n
class Generator(nn.Module):\n    "Define standard linear + softmax generation step."\n\n    def __init__(self, d_model, vocab):\n        super(Generator, self).__init__()\n        self.proj = nn.Linear(d_model, vocab)\n\n    def forward(self, x):\n        return log_softmax(self.proj(x), dim=-1)
\n

The Transformer follows this overall architecture using stacked self-attention and point-wise, fully connected layers for both the encoder and decoder, shown in the left and right halves of Figure 1, respectively.

\n

\n

Encoder and Decoder Stacks

\n

Encoder

\n

The encoder is composed of a stack of N=6 identical layers.

\n
def clones(module, N):\n    "Produce N identical layers."\n    return nn.ModuleList([copy.deepcopy(module) for _ in range(N)])
\n
class Encoder(nn.Module):\n    "Core encoder is a stack of N layers"\n\n    def __init__(self, layer, N):\n        super(Encoder, self).__init__()\n        self.layers = clones(layer, N)\n        self.norm = LayerNorm(layer.size)\n\n    def forward(self, x, mask):\n        "Pass the input (and mask) through each layer in turn."\n        for layer in self.layers:\n            x = layer(x, mask)\n        return self.norm(x)
\n

We employ a residual connection (cite) around each of the two sub-layers, followed by layer normalization (cite).

\n
class LayerNorm(nn.Module):\n    "Construct a layernorm module (See citation for details)."\n\n    def __init__(self, features, eps=1e-6):\n        super(LayerNorm, self).__init__()\n        self.a_2 = nn.Parameter(torch.ones(features))\n        self.b_2 = nn.Parameter(torch.zeros(features))\n        self.eps = eps\n\n    def forward(self, x):\n        mean = x.mean(-1, keepdim=True)\n        std = x.std(-1, keepdim=True)\n        return self.a_2 * (x - mean) / (std + self.eps) + self.b_2
\n

That is, the output of each sub-layer is \\mathrm{LayerNorm}(x + \\mathrm{Sublayer}(x)), where \\mathrm{Sublayer}(x) is the function implemented by the sub-layer itself. We apply dropout (cite) to the output of each sub-layer, before it is added to the sub-layer input and normalized.

\n

To facilitate these residual connections, all sub-layers in the model, as well as the embedding layers, produce outputs of dimension d_{\\text{model}}=512.

\n
class SublayerConnection(nn.Module):\n    """\n    A residual connection followed by a layer norm.\n    Note for code simplicity the norm is first as opposed to last.\n    """\n\n    def __init__(self, size, dropout):\n        super(SublayerConnection, self).__init__()\n        self.norm = LayerNorm(size)\n        self.dropout = nn.Dropout(dropout)\n\n    def forward(self, x, sublayer):\n        "Apply residual connection to any sublayer with the same size."\n        return x + self.dropout(sublayer(self.norm(x)))
\n

Each layer has two sub-layers. The first is a multi-head self-attention mechanism, and the second is a simple, position-wise fully connected feed-forward network.

\n
class EncoderLayer(nn.Module):\n    "Encoder is made up of self-attn and feed forward (defined below)"\n\n    def __init__(self, size, self_attn, feed_forward, dropout):\n        super(EncoderLayer, self).__init__()\n        self.self_attn = self_attn\n        self.feed_forward = feed_forward\n        self.sublayer = clones(SublayerConnection(size, dropout), 2)\n        self.size = size\n\n    def forward(self, x, mask):\n        "Follow Figure 1 (left) for connections."\n        x = self.sublayer[0](x, lambda x: self.self_attn(x, x, x, mask))\n        return self.sublayer[1](x, self.feed_forward)
\n

Decoder

\n

The decoder is also composed of a stack of N=6 identical layers.

\n
class Decoder(nn.Module):\n    "Generic N layer decoder with masking."\n\n    def __init__(self, layer, N):\n        super(Decoder, self).__init__()\n        self.layers = clones(layer, N)\n        self.norm = LayerNorm(layer.size)\n\n    def forward(self, x, memory, src_mask, tgt_mask):\n        for layer in self.layers:\n            x = layer(x, memory, src_mask, tgt_mask)\n        return self.norm(x)
\n

In addition to the two sub-layers in each encoder layer, the decoder inserts a third sub-layer, which performs multi-head attention over the output of the encoder stack. Similar to the encoder, we employ residual connections around each of the sub-layers, followed by layer normalization.

\n
class DecoderLayer(nn.Module):\n    "Decoder is made of self-attn, src-attn, and feed forward (defined below)"\n\n    def __init__(self, size, self_attn, src_attn, feed_forward, dropout):\n        super(DecoderLayer, self).__init__()\n        self.size = size\n        self.self_attn = self_attn\n        self.src_attn = src_attn\n        self.feed_forward = feed_forward\n        self.sublayer = clones(SublayerConnection(size, dropout), 3)\n\n    def forward(self, x, memory, src_mask, tgt_mask):\n        "Follow Figure 1 (right) for connections."\n        m = memory\n        x = self.sublayer[0](x, lambda x: self.self_attn(x, x, x, tgt_mask))\n        x = self.sublayer[1](x, lambda x: self.src_attn(x, m, m, src_mask))\n        return self.sublayer[2](x, self.feed_forward)
\n

We also modify the self-attention sub-layer in the decoder stack to prevent positions from attending to subsequent positions. This masking, combined with fact that the output embeddings are offset by one position, ensures that the predictions for position i can depend only on the known outputs at positions less than i.

\n
def subsequent_mask(size):\n    "Mask out subsequent positions."\n    attn_shape = (1, size, size)\n    subsequent_mask = torch.triu(torch.ones(attn_shape), diagonal=1).type(\n        torch.uint8\n    )\n    return subsequent_mask == 0
\n
\n

Below the attention mask shows the position each tgt word (row) is allowed to look at (column). Words are blocked for attending to future words during training.

\n
\n
def example_mask():\n    LS_data = pd.concat(\n        [\n            pd.DataFrame(\n                {\n                    "Subsequent Mask": subsequent_mask(20)[0][x, y].flatten(),\n                    "Window": y,\n                    "Masking": x,\n                }\n            )\n            for y in range(20)\n            for x in range(20)\n        ]\n    )\n\n    return (\n        alt.Chart(LS_data)\n        .mark_rect()\n        .properties(height=250, width=250)\n        .encode(\n            alt.X("Window:O"),\n            alt.Y("Masking:O"),\n            alt.Color("Subsequent Mask:Q", scale=alt.Scale(scheme="viridis")),\n        )\n        .interactive()\n    )\n\n\nshow_example(example_mask)
\n
\n\n
\n\n

Attention

\n

An attention function can be described as mapping a query and a set of key-value pairs to an output, where the query, keys, values, and output are all vectors. The output is computed as a weighted sum of the values, where the weight assigned to each value is computed by a compatibility function of the query with the corresponding key.

\n

We call our particular attention “Scaled Dot-Product Attention”. The input consists of queries and keys of dimension d_k, and values of dimension d_v. We compute the dot products of the query with all keys, divide each by \\sqrt{d_k}, and apply a softmax function to obtain the weights on the values.

\n

\n

In practice, we compute the attention function on a set of queries simultaneously, packed together into a matrix Q. The keys and values are also packed together into matrices K and V. We compute the matrix of outputs as:

\n

\n \\mathrm{Attention}(Q, K, V) = \\mathrm{softmax}(\\frac{QK^T}{\\sqrt{d_k}})V\n

\n
def attention(query, key, value, mask=None, dropout=None):\n    "Compute 'Scaled Dot Product Attention'"\n    d_k = query.size(-1)\n    scores = torch.matmul(query, key.transpose(-2, -1)) / math.sqrt(d_k)\n    if mask is not None:\n        scores = scores.masked_fill(mask == 0, -1e9)\n    p_attn = scores.softmax(dim=-1)\n    if dropout is not None:\n        p_attn = dropout(p_attn)\n    return torch.matmul(p_attn, value), p_attn
\n

The two most commonly used attention functions are additive attention (cite), and dot-product (multiplicative) attention. Dot-product attention is identical to our algorithm, except for the scaling factor of \\frac{1}{\\sqrt{d_k}}. Additive attention computes the compatibility function using a feed-forward network with a single hidden layer. While the two are similar in theoretical complexity, dot-product attention is much faster and more space-efficient in practice, since it can be implemented using highly optimized matrix multiplication code.

\n

While for small values of d_k the two mechanisms perform similarly, additive attention outperforms dot product attention without scaling for larger values of d_k (cite). We suspect that for large values of d_k, the dot products grow large in magnitude, pushing the softmax function into regions where it has extremely small gradients (To illustrate why the dot products get large, assume that the components of q and k are independent random variables with mean 0 and variance 1. Then their dot product, q \\cdot k = \\sum_{i=1}^{d_k} q_ik_i, has mean 0 and variance d_k.). To counteract this effect, we scale the dot products by \\frac{1}{\\sqrt{d_k}}.

\n

\n

Multi-head attention allows the model to jointly attend to information from different representation subspaces at different positions. With a single attention head, averaging inhibits this.

\n

\n\\mathrm{MultiHead}(Q, K, V) =\n \\mathrm{Concat}(\\mathrm{head_1}, ..., \\mathrm{head_h})W^O \\\\\n \\text{where}~\\mathrm{head_i} = \\mathrm{Attention}(QW^Q_i, KW^K_i, VW^V_i)\n

\n

Where the projections are parameter matrices W^Q_i \\in \\mathbb{R}^{d_{\\text{model}} \\times d_k}, W^K_i \\in \\mathbb{R}^{d_{\\text{model}} \\times d_k}, W^V_i \\in \\mathbb{R}^{d_{\\text{model}} \\times d_v} and W^O \\in \\mathbb{R}^{hd_v \\times d_{\\text{model}}}.

\n

In this work we employ h=8 parallel attention layers, or heads. For each of these we use d_k=d_v=d_{\\text{model}}/h=64. Due to the reduced dimension of each head, the total computational cost is similar to that of single-head attention with full dimensionality.

\n
class MultiHeadedAttention(nn.Module):\n    def __init__(self, h, d_model, dropout=0.1):\n        "Take in model size and number of heads."\n        super(MultiHeadedAttention, self).__init__()\n        assert d_model % h == 0\n        # We assume d_v always equals d_k\n        self.d_k = d_model // h\n        self.h = h\n        self.linears = clones(nn.Linear(d_model, d_model), 4)\n        self.attn = None\n        self.dropout = nn.Dropout(p=dropout)\n\n    def forward(self, query, key, value, mask=None):\n        "Implements Figure 2"\n        if mask is not None:\n            # Same mask applied to all h heads.\n            mask = mask.unsqueeze(1)\n        nbatches = query.size(0)\n\n        # 1) Do all the linear projections in batch from d_model => h x d_k\n        query, key, value = [\n            lin(x).view(nbatches, -1, self.h, self.d_k).transpose(1, 2)\n            for lin, x in zip(self.linears, (query, key, value))\n        ]\n\n        # 2) Apply attention on all the projected vectors in batch.\n        x, self.attn = attention(\n            query, key, value, mask=mask, dropout=self.dropout\n        )\n\n        # 3) "Concat" using a view and apply a final linear.\n        x = (\n            x.transpose(1, 2)\n            .contiguous()\n            .view(nbatches, -1, self.h * self.d_k)\n        )\n        del query\n        del key\n        del value\n        return self.linears[-1](x)
\n

Applications of Attention in our Model

\n

The Transformer uses multi-head attention in three different ways: 1) In “encoder-decoder attention” layers, the queries come from the previous decoder layer, and the memory keys and values come from the output of the encoder. This allows every position in the decoder to attend over all positions in the input sequence. This mimics the typical encoder-decoder attention mechanisms in sequence-to-sequence models such as (cite).

\n
    \n

  1. The encoder contains self-attention layers. In a self-attention layer all of the keys, values and queries come from the same place, in this case, the output of the previous layer in the encoder. Each position in the encoder can attend to all positions in the previous layer of the encoder.

    2. \n

  2. Similarly, self-attention layers in the decoder allow each position in the decoder to attend to all positions in the decoder up to and including that position. We need to prevent leftward information flow in the decoder to preserve the auto-regressive property. We implement this inside of scaled dot-product attention by masking out (setting to -\\infty) all values in the input of the softmax which correspond to illegal connections.

    3. \n
\n

Position-wise Feed-Forward Networks

\n

In addition to attention sub-layers, each of the layers in our encoder and decoder contains a fully connected feed-forward network, which is applied to each position separately and identically. This consists of two linear transformations with a ReLU activation in between.

\n

\\mathrm{FFN}(x)=\\max(0, xW_1 + b_1) W_2 + b_2

\n

While the linear transformations are the same across different positions, they use different parameters from layer to layer. Another way of describing this is as two convolutions with kernel size 1. The dimensionality of input and output is d_{\\text{model}}=512, and the inner-layer has dimensionality d_{ff}=2048.

\n
class PositionwiseFeedForward(nn.Module):\n    "Implements FFN equation."\n\n    def __init__(self, d_model, d_ff, dropout=0.1):\n        super(PositionwiseFeedForward, self).__init__()\n        self.w_1 = nn.Linear(d_model, d_ff)\n        self.w_2 = nn.Linear(d_ff, d_model)\n        self.dropout = nn.Dropout(dropout)\n\n    def forward(self, x):\n        return self.w_2(self.dropout(self.w_1(x).relu()))
\n

Embeddings and Softmax

\n

Similarly to other sequence transduction models, we use learned embeddings to convert the input tokens and output tokens to vectors of dimension d_{\\text{model}}. We also use the usual learned linear transformation and softmax function to convert the decoder output to predicted next-token probabilities. In our model, we share the same weight matrix between the two embedding layers and the pre-softmax linear transformation, similar to (cite). In the embedding layers, we multiply those weights by \\sqrt{d_{\\text{model}}}.

\n
class Embeddings(nn.Module):\n    def __init__(self, d_model, vocab):\n        super(Embeddings, self).__init__()\n        self.lut = nn.Embedding(vocab, d_model)\n        self.d_model = d_model\n\n    def forward(self, x):\n        return self.lut(x) * math.sqrt(self.d_model)
\n

Positional Encoding

\n

Since our model contains no recurrence and no convolution, in order for the model to make use of the order of the sequence, we must inject some information about the relative or absolute position of the tokens in the sequence. To this end, we add “positional encodings” to the input embeddings at the bottoms of the encoder and decoder stacks. The positional encodings have the same dimension d_{\\text{model}} as the embeddings, so that the two can be summed. There are many choices of positional encodings, learned and fixed (cite).

\n

In this work, we use sine and cosine functions of different frequencies:

\n

PE_{(pos,2i)} = \\sin(pos / 10000^{2i/d_{\\text{model}}})

\n

PE_{(pos,2i+1)} = \\cos(pos / 10000^{2i/d_{\\text{model}}})

\n

where pos is the position and i is the dimension. That is, each dimension of the positional encoding corresponds to a sinusoid. The wavelengths form a geometric progression from 2\\pi to 10000 \\cdot 2\\pi. We chose this function because we hypothesized it would allow the model to easily learn to attend by relative positions, since for any fixed offset k, PE_{pos+k} can be represented as a linear function of PE_{pos}.

\n

In addition, we apply dropout to the sums of the embeddings and the positional encodings in both the encoder and decoder stacks. For the base model, we use a rate of P_{drop}=0.1.

\n
class PositionalEncoding(nn.Module):\n    "Implement the PE function."\n\n    def __init__(self, d_model, dropout, max_len=5000):\n        super(PositionalEncoding, self).__init__()\n        self.dropout = nn.Dropout(p=dropout)\n\n        # Compute the positional encodings once in log space.\n        pe = torch.zeros(max_len, d_model)\n        position = torch.arange(0, max_len).unsqueeze(1)\n        div_term = torch.exp(\n            torch.arange(0, d_model, 2) * -(math.log(10000.0) / d_model)\n        )\n        pe[:, 0::2] = torch.sin(position * div_term)\n        pe[:, 1::2] = torch.cos(position * div_term)\n        pe = pe.unsqueeze(0)\n        self.register_buffer("pe", pe)\n\n    def forward(self, x):\n        x = x + self.pe[:, : x.size(1)].requires_grad_(False)\n        return self.dropout(x)
\n
\n

Below the positional encoding will add in a sine wave based on position. The frequency and offset of the wave is different for each dimension.

\n
\n
def example_positional():\n    pe = PositionalEncoding(20, 0)\n    y = pe.forward(torch.zeros(1, 100, 20))\n\n    data = pd.concat(\n        [\n            pd.DataFrame(\n                {\n                    "embedding": y[0, :, dim],\n                    "dimension": dim,\n                    "position": list(range(100)),\n                }\n            )\n            for dim in [4, 5, 6, 7]\n        ]\n    )\n\n    return (\n        alt.Chart(data)\n        .mark_line()\n        .properties(width=800)\n        .encode(x="position", y="embedding", color="dimension:N")\n        .interactive()\n    )\n\n\nshow_example(example_positional)
\n
\n\n
\n\n

We also experimented with using learned positional embeddings (cite) instead, and found that the two versions produced nearly identical results. We chose the sinusoidal version because it may allow the model to extrapolate to sequence lengths longer than the ones encountered during training.

\n

Full Model

\n
\n

Here we define a function from hyperparameters to a full model.

\n
\n
def make_model(\n    src_vocab, tgt_vocab, N=6, d_model=512, d_ff=2048, h=8, dropout=0.1\n):\n    "Helper: Construct a model from hyperparameters."\n    c = copy.deepcopy\n    attn = MultiHeadedAttention(h, d_model)\n    ff = PositionwiseFeedForward(d_model, d_ff, dropout)\n    position = PositionalEncoding(d_model, dropout)\n    model = EncoderDecoder(\n        Encoder(EncoderLayer(d_model, c(attn), c(ff), dropout), N),\n        Decoder(DecoderLayer(d_model, c(attn), c(attn), c(ff), dropout), N),\n        nn.Sequential(Embeddings(d_model, src_vocab), c(position)),\n        nn.Sequential(Embeddings(d_model, tgt_vocab), c(position)),\n        Generator(d_model, tgt_vocab),\n    )\n\n    # This was important from their code.\n    # Initialize parameters with Glorot / fan_avg.\n    for p in model.parameters():\n        if p.dim() > 1:\n            nn.init.xavier_uniform_(p)\n    return model
\n

Inference:

\n
\n

Here we make a forward step to generate a prediction of the model. We try to use our transformer to memorize the input. As you will see the output is randomly generated due to the fact that the model is not trained yet. In the next tutorial we will build the training function and try to train our model to memorize the numbers from 1 to 10.

\n
\n
def inference_test():\n    test_model = make_model(11, 11, 2)\n    test_model.eval()\n    src = torch.LongTensor([[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]])\n    src_mask = torch.ones(1, 1, 10)\n\n    memory = test_model.encode(src, src_mask)\n    ys = torch.zeros(1, 1).type_as(src)\n\n    for i in range(9):\n        out = test_model.decode(\n            memory, src_mask, ys, subsequent_mask(ys.size(1)).type_as(src.data)\n        )\n        prob = test_model.generator(out[:, -1])\n        _, next_word = torch.max(prob, dim=1)\n        next_word = next_word.data[0]\n        ys = torch.cat(\n            [ys, torch.empty(1, 1).type_as(src.data).fill_(next_word)], dim=1\n        )\n\n    print("Example Untrained Model Prediction:", ys)\n\n\ndef run_tests():\n    for _ in range(10):\n        inference_test()\n\n\nshow_example(run_tests)
\n
Example Untrained Model Prediction: tensor([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])\nExample Untrained Model Prediction: tensor([[0, 3, 4, 4, 4, 4, 4, 4, 4, 4]])\nExample Untrained Model Prediction: tensor([[ 0, 10, 10, 10,  3,  2,  5,  7,  9,  6]])\nExample Untrained Model Prediction: tensor([[ 0,  4,  3,  6, 10, 10,  2,  6,  2,  2]])\nExample Untrained Model Prediction: tensor([[ 0,  9,  0,  1,  5, 10,  1,  5, 10,  6]])\nExample Untrained Model Prediction: tensor([[ 0,  1,  5,  1, 10,  1, 10, 10, 10, 10]])\nExample Untrained Model Prediction: tensor([[ 0,  1, 10,  9,  9,  9,  9,  9,  1,  5]])\nExample Untrained Model Prediction: tensor([[ 0,  3,  1,  5, 10, 10, 10, 10, 10, 10]])\nExample Untrained Model Prediction: tensor([[ 0,  3,  5, 10,  5, 10,  4,  2,  4,  2]])\nExample Untrained Model Prediction: tensor([[0, 5, 6, 2, 5, 6, 2, 6, 2, 2]])
\n

Part 2: Model Training

\n

Training

\n

This section describes the training regime for our models.

\n
\n

We stop for a quick interlude to introduce some of the tools needed to train a standard encoder decoder model. First we define a batch object that holds the src and target sentences for training, as well as constructing the masks.

\n
\n

Batches and Masking

\n
class Batch:\n    """Object for holding a batch of data with mask during training."""\n\n    def __init__(self, src, tgt=None, pad=2):  # 2 = <blank>\n        self.src = src\n        self.src_mask = (src != pad).unsqueeze(-2)\n        if tgt is not None:\n            self.tgt = tgt[:, :-1]\n            self.tgt_y = tgt[:, 1:]\n            self.tgt_mask = self.make_std_mask(self.tgt, pad)\n            self.ntokens = (self.tgt_y != pad).data.sum()\n\n    @staticmethod\n    def make_std_mask(tgt, pad):\n        "Create a mask to hide padding and future words."\n        tgt_mask = (tgt != pad).unsqueeze(-2)\n        tgt_mask = tgt_mask & subsequent_mask(tgt.size(-1)).type_as(\n            tgt_mask.data\n        )\n        return tgt_mask
\n
\n

Next we create a generic training and scoring function to keep track of loss. We pass in a generic loss compute function that also handles parameter updates.

\n
\n

Training Loop

\n
class TrainState:\n    """Track number of steps, examples, and tokens processed"""\n\n    step: int = 0  # Steps in the current epoch\n    accum_step: int = 0  # Number of gradient accumulation steps\n    samples: int = 0  # total # of examples used\n    tokens: int = 0  # total # of tokens processed
\n
def run_epoch(\n    data_iter,\n    model,\n    loss_compute,\n    optimizer,\n    scheduler,\n    mode="train",\n    accum_iter=1,\n    train_state=TrainState(),\n):\n    """Train a single epoch"""\n    start = time.time()\n    total_tokens = 0\n    total_loss = 0\n    tokens = 0\n    n_accum = 0\n    for i, batch in enumerate(data_iter):\n        out = model.forward(\n            batch.src, batch.tgt, batch.src_mask, batch.tgt_mask\n        )\n        loss, loss_node = loss_compute(out, batch.tgt_y, batch.ntokens)\n        # loss_node = loss_node / accum_iter\n        if mode == "train" or mode == "train+log":\n            loss_node.backward()\n            train_state.step += 1\n            train_state.samples += batch.src.shape[0]\n            train_state.tokens += batch.ntokens\n            if i % accum_iter == 0:\n                optimizer.step()\n                optimizer.zero_grad(set_to_none=True)\n                n_accum += 1\n                train_state.accum_step += 1\n            scheduler.step()\n\n        total_loss += loss\n        total_tokens += batch.ntokens\n        tokens += batch.ntokens\n        if i % 40 == 1 and (mode == "train" or mode == "train+log"):\n            lr = optimizer.param_groups[0]["lr"]\n            elapsed = time.time() - start\n            print(\n                (\n                    "Epoch Step: %6d | Accumulation Step: %3d | Loss: %6.2f "\n                    + "| Tokens / Sec: %7.1f | Learning Rate: %6.1e"\n                )\n                % (i, n_accum, loss / batch.ntokens, tokens / elapsed, lr)\n            )\n            start = time.time()\n            tokens = 0\n        del loss\n        del loss_node\n    return total_loss / total_tokens, train_state
\n

Training Data and Batching

\n

We trained on the standard WMT 2014 English-German dataset consisting of about 4.5 million sentence pairs. Sentences were encoded using byte-pair encoding, which has a shared source-target vocabulary of about 37000 tokens. For English-French, we used the significantly larger WMT 2014 English-French dataset consisting of 36M sentences and split tokens into a 32000 word-piece vocabulary.

\n

Sentence pairs were batched together by approximate sequence length. Each training batch contained a set of sentence pairs containing approximately 25000 source tokens and 25000 target tokens.

\n

Hardware and Schedule

\n

We trained our models on one machine with 8 NVIDIA P100 GPUs. For our base models using the hyperparameters described throughout the paper, each training step took about 0.4 seconds. We trained the base models for a total of 100,000 steps or 12 hours. For our big models, step time was 1.0 seconds. The big models were trained for 300,000 steps (3.5 days).

\n

Optimizer

\n

We used the Adam optimizer (cite) with \\beta_1=0.9, \\beta_2=0.98 and \\epsilon=10^{-9}. We varied the learning rate over the course of training, according to the formula:

\n

\nlrate = d_{\\text{model}}^{-0.5} \\cdot\n \\min({step\\_num}^{-0.5},\n {step\\_num} \\cdot {warmup\\_steps}^{-1.5})\n

\n

This corresponds to increasing the learning rate linearly for the first warmup\\_steps training steps, and decreasing it thereafter proportionally to the inverse square root of the step number. We used warmup\\_steps=4000.

\n
\n

Note: This part is very important. Need to train with this setup of the model.

\n
\n
\n

Example of the curves of this model for different model sizes and for optimization hyperparameters.

\n
\n
def rate(step, model_size, factor, warmup):\n    """\n    we have to default the step to 1 for LambdaLR function\n    to avoid zero raising to negative power.\n    """\n    if step == 0:\n        step = 1\n    return factor * (\n        model_size ** (-0.5) * min(step ** (-0.5), step * warmup ** (-1.5))\n    )
\n
def example_learning_schedule():\n    opts = [\n        [512, 1, 4000],  # example 1\n        [512, 1, 8000],  # example 2\n        [256, 1, 4000],  # example 3\n    ]\n\n    dummy_model = torch.nn.Linear(1, 1)\n    learning_rates = []\n\n    # we have 3 examples in opts list.\n    for idx, example in enumerate(opts):\n        # run 20000 epoch for each example\n        optimizer = torch.optim.Adam(\n            dummy_model.parameters(), lr=1, betas=(0.9, 0.98), eps=1e-9\n        )\n        lr_scheduler = LambdaLR(\n            optimizer=optimizer, lr_lambda=lambda step: rate(step, *example)\n        )\n        tmp = []\n        # take 20K dummy training steps, save the learning rate at each step\n        for step in range(20000):\n            tmp.append(optimizer.param_groups[0]["lr"])\n            optimizer.step()\n            lr_scheduler.step()\n        learning_rates.append(tmp)\n\n    learning_rates = torch.tensor(learning_rates)\n\n    # Enable altair to handle more than 5000 rows\n    alt.data_transformers.disable_max_rows()\n\n    opts_data = pd.concat(\n        [\n            pd.DataFrame(\n                {\n                    "Learning Rate": learning_rates[warmup_idx, :],\n                    "model_size:warmup": ["512:4000", "512:8000", "256:4000"][\n                        warmup_idx\n                    ],\n                    "step": range(20000),\n                }\n            )\n            for warmup_idx in [0, 1, 2]\n        ]\n    )\n\n    return (\n        alt.Chart(opts_data)\n        .mark_line()\n        .properties(width=600)\n        .encode(x="step", y="Learning Rate", color="model_size:warmup:N")\n        .interactive()\n    )\n\n\nexample_learning_schedule()
\n
\n\n
\n\n

Regularization

\n

Label Smoothing

\n

During training, we employed label smoothing of value \\epsilon_{ls}=0.1 (cite). This hurts perplexity, as the model learns to be more unsure, but improves accuracy and BLEU score.

\n
\n

We implement label smoothing using the KL div loss. Instead of using a one-hot target distribution, we create a distribution that has confidence of the correct word and the rest of the smoothing mass distributed throughout the vocabulary.

\n
\n
class LabelSmoothing(nn.Module):\n    "Implement label smoothing."\n\n    def __init__(self, size, padding_idx, smoothing=0.0):\n        super(LabelSmoothing, self).__init__()\n        self.criterion = nn.KLDivLoss(reduction="sum")\n        self.padding_idx = padding_idx\n        self.confidence = 1.0 - smoothing\n        self.smoothing = smoothing\n        self.size = size\n        self.true_dist = None\n\n    def forward(self, x, target):\n        assert x.size(1) == self.size\n        true_dist = x.data.clone()\n        true_dist.fill_(self.smoothing / (self.size - 2))\n        true_dist.scatter_(1, target.data.unsqueeze(1), self.confidence)\n        true_dist[:, self.padding_idx] = 0\n        mask = torch.nonzero(target.data == self.padding_idx)\n        if mask.dim() > 0:\n            true_dist.index_fill_(0, mask.squeeze(), 0.0)\n        self.true_dist = true_dist\n        return self.criterion(x, true_dist.clone().detach())
\n
\n

Here we can see an example of how the mass is distributed to the words based on confidence.

\n
\n
# Example of label smoothing.\n\n\ndef example_label_smoothing():\n    crit = LabelSmoothing(5, 0, 0.4)\n    predict = torch.FloatTensor(\n        [\n            [0, 0.2, 0.7, 0.1, 0],\n            [0, 0.2, 0.7, 0.1, 0],\n            [0, 0.2, 0.7, 0.1, 0],\n            [0, 0.2, 0.7, 0.1, 0],\n            [0, 0.2, 0.7, 0.1, 0],\n        ]\n    )\n    crit(x=predict.log(), target=torch.LongTensor([2, 1, 0, 3, 3]))\n    LS_data = pd.concat(\n        [\n            pd.DataFrame(\n                {\n                    "target distribution": crit.true_dist[x, y].flatten(),\n                    "columns": y,\n                    "rows": x,\n                }\n            )\n            for y in range(5)\n            for x in range(5)\n        ]\n    )\n\n    return (\n        alt.Chart(LS_data)\n        .mark_rect(color="Blue", opacity=1)\n        .properties(height=200, width=200)\n        .encode(\n            alt.X("columns:O", title=None),\n            alt.Y("rows:O", title=None),\n            alt.Color(\n                "target distribution:Q", scale=alt.Scale(scheme="viridis")\n            ),\n        )\n        .interactive()\n    )\n\n\nshow_example(example_label_smoothing)
\n
\n\n
\n\n
\n

Label smoothing actually starts to penalize the model if it gets very confident about a given choice.

\n
\n
\n\ndef loss(x, crit):\n    d = x + 3 * 1\n    predict = torch.FloatTensor([[0, x / d, 1 / d, 1 / d, 1 / d]])\n    return crit(predict.log(), torch.LongTensor([1])).data\n\n\ndef penalization_visualization():\n    crit = LabelSmoothing(5, 0, 0.1)\n    loss_data = pd.DataFrame(\n        {\n            "Loss": [loss(x, crit) for x in range(1, 100)],\n            "Steps": list(range(99)),\n        }\n    ).astype("float")\n\n    return (\n        alt.Chart(loss_data)\n        .mark_line()\n        .properties(width=350)\n        .encode(\n            x="Steps",\n            y="Loss",\n        )\n        .interactive()\n    )\n\n\nshow_example(penalization_visualization)
\n
\n\n
\n\n

A First Example

\n
\n

We can begin by trying out a simple copy-task. Given a random set of input symbols from a small vocabulary, the goal is to generate back those same symbols.

\n
\n

Synthetic Data

\n
def data_gen(V, batch_size, nbatches):\n    "Generate random data for a src-tgt copy task."\n    for i in range(nbatches):\n        data = torch.randint(1, V, size=(batch_size, 10))\n        data[:, 0] = 1\n        src = data.requires_grad_(False).clone().detach()\n        tgt = data.requires_grad_(False).clone().detach()\n        yield Batch(src, tgt, 0)
\n

Loss Computation

\n
class SimpleLossCompute:\n    "A simple loss compute and train function."\n\n    def __init__(self, generator, criterion):\n        self.generator = generator\n        self.criterion = criterion\n\n    def __call__(self, x, y, norm):\n        x = self.generator(x)\n        sloss = (\n            self.criterion(\n                x.contiguous().view(-1, x.size(-1)), y.contiguous().view(-1)\n            )\n            / norm\n        )\n        return sloss.data * norm, sloss
\n

Greedy Decoding

\n
\n

This code predicts a translation using greedy decoding for simplicity.

\n
\n
def greedy_decode(model, src, src_mask, max_len, start_symbol):\n    memory = model.encode(src, src_mask)\n    ys = torch.zeros(1, 1).fill_(start_symbol).type_as(src.data)\n    for i in range(max_len - 1):\n        out = model.decode(\n            memory, src_mask, ys, subsequent_mask(ys.size(1)).type_as(src.data)\n        )\n        prob = model.generator(out[:, -1])\n        _, next_word = torch.max(prob, dim=1)\n        next_word = next_word.data[0]\n        ys = torch.cat(\n            [ys, torch.zeros(1, 1).type_as(src.data).fill_(next_word)], dim=1\n        )\n    return ys
\n
# Train the simple copy task.\n\n\ndef example_simple_model():\n    V = 11\n    criterion = LabelSmoothing(size=V, padding_idx=0, smoothing=0.0)\n    model = make_model(V, V, N=2)\n\n    optimizer = torch.optim.Adam(\n        model.parameters(), lr=0.5, betas=(0.9, 0.98), eps=1e-9\n    )\n    lr_scheduler = LambdaLR(\n        optimizer=optimizer,\n        lr_lambda=lambda step: rate(\n            step, model_size=model.src_embed[0].d_model, factor=1.0, warmup=400\n        ),\n    )\n\n    batch_size = 80\n    for epoch in range(20):\n        model.train()\n        run_epoch(\n            data_gen(V, batch_size, 20),\n            model,\n            SimpleLossCompute(model.generator, criterion),\n            optimizer,\n            lr_scheduler,\n            mode="train",\n        )\n        model.eval()\n        run_epoch(\n            data_gen(V, batch_size, 5),\n            model,\n            SimpleLossCompute(model.generator, criterion),\n            DummyOptimizer(),\n            DummyScheduler(),\n            mode="eval",\n        )[0]\n\n    model.eval()\n    src = torch.LongTensor([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]])\n    max_len = src.shape[1]\n    src_mask = torch.ones(1, 1, max_len)\n    print(greedy_decode(model, src, src_mask, max_len=max_len, start_symbol=0))\n\n\n# execute_example(example_simple_model)
\n

Part 3: A Real World Example

\n
\n

Now we consider a real-world example using the Multi30k German-English Translation task. This task is much smaller than the WMT task considered in the paper, but it illustrates the whole system. We also show how to use multi-gpu processing to make it really fast.

\n
\n

Data Loading

\n
\n

We will load the dataset using torchtext and spacy for tokenization.

\n
\n
# Load spacy tokenizer models, download them if they haven't been\n# downloaded already\n\n\ndef load_tokenizers():\n\n    try:\n        spacy_de = spacy.load("de_core_news_sm")\n    except IOError:\n        os.system("python -m spacy download de_core_news_sm")\n        spacy_de = spacy.load("de_core_news_sm")\n\n    try:\n        spacy_en = spacy.load("en_core_web_sm")\n    except IOError:\n        os.system("python -m spacy download en_core_web_sm")\n        spacy_en = spacy.load("en_core_web_sm")\n\n    return spacy_de, spacy_en
\n
def tokenize(text, tokenizer):\n    return [tok.text for tok in tokenizer.tokenizer(text)]\n\n\ndef yield_tokens(data_iter, tokenizer, index):\n    for from_to_tuple in data_iter:\n        yield tokenizer(from_to_tuple[index])
\n
\n\ndef build_vocabulary(spacy_de, spacy_en):\n    def tokenize_de(text):\n        return tokenize(text, spacy_de)\n\n    def tokenize_en(text):\n        return tokenize(text, spacy_en)\n\n    print("Building German Vocabulary ...")\n    train, val, test = datasets.Multi30k(language_pair=("de", "en"))\n    vocab_src = build_vocab_from_iterator(\n        yield_tokens(train + val + test, tokenize_de, index=0),\n        min_freq=2,\n        specials=["<s>", "</s>", "<blank>", "<unk>"],\n    )\n\n    print("Building English Vocabulary ...")\n    train, val, test = datasets.Multi30k(language_pair=("de", "en"))\n    vocab_tgt = build_vocab_from_iterator(\n        yield_tokens(train + val + test, tokenize_en, index=1),\n        min_freq=2,\n        specials=["<s>", "</s>", "<blank>", "<unk>"],\n    )\n\n    vocab_src.set_default_index(vocab_src["<unk>"])\n    vocab_tgt.set_default_index(vocab_tgt["<unk>"])\n\n    return vocab_src, vocab_tgt\n\n\ndef load_vocab(spacy_de, spacy_en):\n    if not exists("vocab.pt"):\n        vocab_src, vocab_tgt = build_vocabulary(spacy_de, spacy_en)\n        torch.save((vocab_src, vocab_tgt), "vocab.pt")\n    else:\n        vocab_src, vocab_tgt = torch.load("vocab.pt")\n    print("Finished.\\nVocabulary sizes:")\n    print(len(vocab_src))\n    print(len(vocab_tgt))\n    return vocab_src, vocab_tgt\n\n\nif is_interactive_notebook():\n    # global variables used later in the script\n    spacy_de, spacy_en = show_example(load_tokenizers)\n    vocab_src, vocab_tgt = show_example(load_vocab, args=[spacy_de, spacy_en])
\n
Finished.\nVocabulary sizes:\n59981\n36745
\n
\n

Batching matters a ton for speed. We want to have very evenly divided batches, with absolutely minimal padding. To do this we have to hack a bit around the default torchtext batching. This code patches their default batching to make sure we search over enough sentences to find tight batches.

\n
\n

Iterators

\n
def collate_batch(\n    batch,\n    src_pipeline,\n    tgt_pipeline,\n    src_vocab,\n    tgt_vocab,\n    device,\n    max_padding=128,\n    pad_id=2,\n):\n    bs_id = torch.tensor([0], device=device)  # <s> token id\n    eos_id = torch.tensor([1], device=device)  # </s> token id\n    src_list, tgt_list = [], []\n    for (_src, _tgt) in batch:\n        processed_src = torch.cat(\n            [\n                bs_id,\n                torch.tensor(\n                    src_vocab(src_pipeline(_src)),\n                    dtype=torch.int64,\n                    device=device,\n                ),\n                eos_id,\n            ],\n            0,\n        )\n        processed_tgt = torch.cat(\n            [\n                bs_id,\n                torch.tensor(\n                    tgt_vocab(tgt_pipeline(_tgt)),\n                    dtype=torch.int64,\n                    device=device,\n                ),\n                eos_id,\n            ],\n            0,\n        )\n        src_list.append(\n            # warning - overwrites values for negative values of padding - len\n            pad(\n                processed_src,\n                (\n                    0,\n                    max_padding - len(processed_src),\n                ),\n                value=pad_id,\n            )\n        )\n        tgt_list.append(\n            pad(\n                processed_tgt,\n                (0, max_padding - len(processed_tgt)),\n                value=pad_id,\n            )\n        )\n\n    src = torch.stack(src_list)\n    tgt = torch.stack(tgt_list)\n    return (src, tgt)
\n
def create_dataloaders(\n    device,\n    vocab_src,\n    vocab_tgt,\n    spacy_de,\n    spacy_en,\n    batch_size=12000,\n    max_padding=128,\n    is_distributed=True,\n):\n    # def create_dataloaders(batch_size=12000):\n    def tokenize_de(text):\n        return tokenize(text, spacy_de)\n\n    def tokenize_en(text):\n        return tokenize(text, spacy_en)\n\n    def collate_fn(batch):\n        return collate_batch(\n            batch,\n            tokenize_de,\n            tokenize_en,\n            vocab_src,\n            vocab_tgt,\n            device,\n            max_padding=max_padding,\n            pad_id=vocab_src.get_stoi()["<blank>"],\n        )\n\n    train_iter, valid_iter, test_iter = datasets.Multi30k(\n        language_pair=("de", "en")\n    )\n\n    train_iter_map = to_map_style_dataset(\n        train_iter\n    )  # DistributedSampler needs a dataset len()\n    train_sampler = (\n        DistributedSampler(train_iter_map) if is_distributed else None\n    )\n    valid_iter_map = to_map_style_dataset(valid_iter)\n    valid_sampler = (\n        DistributedSampler(valid_iter_map) if is_distributed else None\n    )\n\n    train_dataloader = DataLoader(\n        train_iter_map,\n        batch_size=batch_size,\n        shuffle=(train_sampler is None),\n        sampler=train_sampler,\n        collate_fn=collate_fn,\n    )\n    valid_dataloader = DataLoader(\n        valid_iter_map,\n        batch_size=batch_size,\n        shuffle=(valid_sampler is None),\n        sampler=valid_sampler,\n        collate_fn=collate_fn,\n    )\n    return train_dataloader, valid_dataloader
\n

Training the System

\n
def train_worker(\n    gpu,\n    ngpus_per_node,\n    vocab_src,\n    vocab_tgt,\n    spacy_de,\n    spacy_en,\n    config,\n    is_distributed=False,\n):\n    print(f"Train worker process using GPU: {gpu} for training", flush=True)\n    torch.cuda.set_device(gpu)\n\n    pad_idx = vocab_tgt["<blank>"]\n    d_model = 512\n    model = make_model(len(vocab_src), len(vocab_tgt), N=6)\n    model.cuda(gpu)\n    module = model\n    is_main_process = True\n    if is_distributed:\n        dist.init_process_group(\n            "nccl", init_method="env://", rank=gpu, world_size=ngpus_per_node\n        )\n        model = DDP(model, device_ids=[gpu])\n        module = model.module\n        is_main_process = gpu == 0\n\n    criterion = LabelSmoothing(\n        size=len(vocab_tgt), padding_idx=pad_idx, smoothing=0.1\n    )\n    criterion.cuda(gpu)\n\n    train_dataloader, valid_dataloader = create_dataloaders(\n        gpu,\n        vocab_src,\n        vocab_tgt,\n        spacy_de,\n        spacy_en,\n        batch_size=config["batch_size"] // ngpus_per_node,\n        max_padding=config["max_padding"],\n        is_distributed=is_distributed,\n    )\n\n    optimizer = torch.optim.Adam(\n        model.parameters(), lr=config["base_lr"], betas=(0.9, 0.98), eps=1e-9\n    )\n    lr_scheduler = LambdaLR(\n        optimizer=optimizer,\n        lr_lambda=lambda step: rate(\n            step, d_model, factor=1, warmup=config["warmup"]\n        ),\n    )\n    train_state = TrainState()\n\n    for epoch in range(config["num_epochs"]):\n        if is_distributed:\n            train_dataloader.sampler.set_epoch(epoch)\n            valid_dataloader.sampler.set_epoch(epoch)\n\n        model.train()\n        print(f"[GPU{gpu}] Epoch {epoch} Training ====", flush=True)\n        _, train_state = run_epoch(\n            (Batch(b[0], b[1], pad_idx) for b in train_dataloader),\n            model,\n            SimpleLossCompute(module.generator, criterion),\n            optimizer,\n            lr_scheduler,\n            mode="train+log",\n            accum_iter=config["accum_iter"],\n            train_state=train_state,\n        )\n\n        GPUtil.showUtilization()\n        if is_main_process:\n            file_path = "%s%.2d.pt" % (config["file_prefix"], epoch)\n            torch.save(module.state_dict(), file_path)\n        torch.cuda.empty_cache()\n\n        print(f"[GPU{gpu}] Epoch {epoch} Validation ====", flush=True)\n        model.eval()\n        sloss = run_epoch(\n            (Batch(b[0], b[1], pad_idx) for b in valid_dataloader),\n            model,\n            SimpleLossCompute(module.generator, criterion),\n            DummyOptimizer(),\n            DummyScheduler(),\n            mode="eval",\n        )\n        print(sloss)\n        torch.cuda.empty_cache()\n\n    if is_main_process:\n        file_path = "%sfinal.pt" % config["file_prefix"]\n        torch.save(module.state_dict(), file_path)
\n
def train_distributed_model(vocab_src, vocab_tgt, spacy_de, spacy_en, config):\n    from the_annotated_transformer import train_worker\n\n    ngpus = torch.cuda.device_count()\n    os.environ["MASTER_ADDR"] = "localhost"\n    os.environ["MASTER_PORT"] = "12356"\n    print(f"Number of GPUs detected: {ngpus}")\n    print("Spawning training processes ...")\n    mp.spawn(\n        train_worker,\n        nprocs=ngpus,\n        args=(ngpus, vocab_src, vocab_tgt, spacy_de, spacy_en, config, True),\n    )\n\n\ndef train_model(vocab_src, vocab_tgt, spacy_de, spacy_en, config):\n    if config["distributed"]:\n        train_distributed_model(\n            vocab_src, vocab_tgt, spacy_de, spacy_en, config\n        )\n    else:\n        train_worker(\n            0, 1, vocab_src, vocab_tgt, spacy_de, spacy_en, config, False\n        )\n\n\ndef load_trained_model():\n    config = {\n        "batch_size": 32,\n        "distributed": False,\n        "num_epochs": 8,\n        "accum_iter": 10,\n        "base_lr": 1.0,\n        "max_padding": 72,\n        "warmup": 3000,\n        "file_prefix": "multi30k_model_",\n    }\n    model_path = "multi30k_model_final.pt"\n    if not exists(model_path):\n        train_model(vocab_src, vocab_tgt, spacy_de, spacy_en, config)\n\n    model = make_model(len(vocab_src), len(vocab_tgt), N=6)\n    model.load_state_dict(torch.load("multi30k_model_final.pt"))\n    return model\n\n\nif is_interactive_notebook():\n    model = load_trained_model()
\n
\n

Once trained we can decode the model to produce a set of translations. Here we simply translate the first sentence in the validation set. This dataset is pretty small so the translations with greedy search are reasonably accurate.

\n
\n

Additional Components: BPE, Search, Averaging

\n
\n

So this mostly covers the transformer model itself. There are four aspects that we didn’t cover explicitly. We also have all these additional features implemented in OpenNMT-py.

\n
\n
\n
    \n
  1. BPE/ Word-piece: We can use a library to first preprocess the data into subword units. See Rico Sennrich’s subword-nmt implementation. These models will transform the training data to look like this:
    2. \n
\n
\n

▁Die ▁Protokoll datei ▁kann ▁ heimlich ▁per ▁E - Mail ▁oder ▁FTP ▁an ▁einen ▁bestimmte n ▁Empfänger ▁gesendet ▁werden .

\n
\n
    \n
  1. Shared Embeddings: When using BPE with shared vocabulary we can share the same weight vectors between the source / target / generator. See the (cite) for details. To add this to the model simply do this:
    2. \n
\n
\n
if False:\n    model.src_embed[0].lut.weight = model.tgt_embeddings[0].lut.weight\n    model.generator.lut.weight = model.tgt_embed[0].lut.weight
\n
\n
    \n
  1. Beam Search: This is a bit too complicated to cover here. See the OpenNMT-py for a pytorch implementation.
    2. \n
\n
\n
\n
    \n
  1. Model Averaging: The paper averages the last k checkpoints to create an ensembling effect. We can do this after the fact if we have a bunch of models:
    2. \n
\n
\n
def average(model, models):\n    "Average models into model"\n    for ps in zip(*[m.params() for m in [model] + models]):\n        ps[0].copy_(torch.sum(*ps[1:]) / len(ps[1:]))
\n

Results

\n

On the WMT 2014 English-to-German translation task, the big transformer model (Transformer (big) in Table 2) outperforms the best previously reported models (including ensembles) by more than 2.0 BLEU, establishing a new state-of-the-art BLEU score of 28.4. The configuration of this model is listed in the bottom line of Table 3. Training took 3.5 days on 8 P100 GPUs. Even our base model surpasses all previously published models and ensembles, at a fraction of the training cost of any of the competitive models.

\n

On the WMT 2014 English-to-French translation task, our big model achieves a BLEU score of 41.0, outperforming all of the previously published single models, at less than 1/4 the training cost of the previous state-of-the-art model. The Transformer (big) model trained for English-to-French used dropout rate Pdrop = 0.1, instead of 0.3.

\n

\n
\n

With the addtional extensions in the last section, the OpenNMT-py replication gets to 26.9 on EN-DE WMT. Here I have loaded in those parameters to our reimplemenation.

\n
\n
# Load data and model for output checks
\n
def check_outputs(\n    valid_dataloader,\n    model,\n    vocab_src,\n    vocab_tgt,\n    n_examples=15,\n    pad_idx=2,\n    eos_string="</s>",\n):\n    results = [()] * n_examples\n    for idx in range(n_examples):\n        print("\\nExample %d ========\\n" % idx)\n        b = next(iter(valid_dataloader))\n        rb = Batch(b[0], b[1], pad_idx)\n        greedy_decode(model, rb.src, rb.src_mask, 64, 0)[0]\n\n        src_tokens = [\n            vocab_src.get_itos()[x] for x in rb.src[0] if x != pad_idx\n        ]\n        tgt_tokens = [\n            vocab_tgt.get_itos()[x] for x in rb.tgt[0] if x != pad_idx\n        ]\n\n        print(\n            "Source Text (Input)        : "\n            + " ".join(src_tokens).replace("\\n", "")\n        )\n        print(\n            "Target Text (Ground Truth) : "\n            + " ".join(tgt_tokens).replace("\\n", "")\n        )\n        model_out = greedy_decode(model, rb.src, rb.src_mask, 72, 0)[0]\n        model_txt = (\n            " ".join(\n                [vocab_tgt.get_itos()[x] for x in model_out if x != pad_idx]\n            ).split(eos_string, 1)[0]\n            + eos_string\n        )\n        print("Model Output               : " + model_txt.replace("\\n", ""))\n        results[idx] = (rb, src_tokens, tgt_tokens, model_out, model_txt)\n    return results\n\n\ndef run_model_example(n_examples=5):\n    global vocab_src, vocab_tgt, spacy_de, spacy_en\n\n    print("Preparing Data ...")\n    _, valid_dataloader = create_dataloaders(\n        torch.device("cpu"),\n        vocab_src,\n        vocab_tgt,\n        spacy_de,\n        spacy_en,\n        batch_size=1,\n        is_distributed=False,\n    )\n\n    print("Loading Trained Model ...")\n\n    model = make_model(len(vocab_src), len(vocab_tgt), N=6)\n    model.load_state_dict(\n        torch.load("multi30k_model_final.pt", map_location=torch.device("cpu"))\n    )\n\n    print("Checking Model Outputs:")\n    example_data = check_outputs(\n        valid_dataloader, model, vocab_src, vocab_tgt, n_examples=n_examples\n    )\n    return model, example_data\n\n\n# execute_example(run_model_example)
\n

Attention Visualization

\n
\n

Even with a greedy decoder the translation looks pretty good. We can further visualize it to see what is happening at each layer of the attention

\n
\n
def mtx2df(m, max_row, max_col, row_tokens, col_tokens):\n    "convert a dense matrix to a data frame with row and column indices"\n    return pd.DataFrame(\n        [\n            (\n                r,\n                c,\n                float(m[r, c]),\n                "%.3d %s"\n                % (r, row_tokens[r] if len(row_tokens) > r else "<blank>"),\n                "%.3d %s"\n                % (c, col_tokens[c] if len(col_tokens) > c else "<blank>"),\n            )\n            for r in range(m.shape[0])\n            for c in range(m.shape[1])\n            if r < max_row and c < max_col\n        ],\n        # if float(m[r,c]) != 0 and r < max_row and c < max_col],\n        columns=["row", "column", "value", "row_token", "col_token"],\n    )\n\n\ndef attn_map(attn, layer, head, row_tokens, col_tokens, max_dim=30):\n    df = mtx2df(\n        attn[0, head].data,\n        max_dim,\n        max_dim,\n        row_tokens,\n        col_tokens,\n    )\n    return (\n        alt.Chart(data=df)\n        .mark_rect()\n        .encode(\n            x=alt.X("col_token", axis=alt.Axis(title="")),\n            y=alt.Y("row_token", axis=alt.Axis(title="")),\n            color="value",\n            tooltip=["row", "column", "value", "row_token", "col_token"],\n        )\n        .properties(height=400, width=400)\n        .interactive()\n    )
\n
def get_encoder(model, layer):\n    return model.encoder.layers[layer].self_attn.attn\n\n\ndef get_decoder_self(model, layer):\n    return model.decoder.layers[layer].self_attn.attn\n\n\ndef get_decoder_src(model, layer):\n    return model.decoder.layers[layer].src_attn.attn\n\n\ndef visualize_layer(model, layer, getter_fn, ntokens, row_tokens, col_tokens):\n    # ntokens = last_example[0].ntokens\n    attn = getter_fn(model, layer)\n    n_heads = attn.shape[1]\n    charts = [\n        attn_map(\n            attn,\n            0,\n            h,\n            row_tokens=row_tokens,\n            col_tokens=col_tokens,\n            max_dim=ntokens,\n        )\n        for h in range(n_heads)\n    ]\n    assert n_heads == 8\n    return alt.vconcat(\n        charts[0]\n        # | charts[1]\n        | charts[2]\n        # | charts[3]\n        | charts[4]\n        # | charts[5]\n        | charts[6]\n        # | charts[7]\n        # layer + 1 due to 0-indexing\n    ).properties(title="Layer %d" % (layer + 1))
\n

Encoder Self Attention

\n
def viz_encoder_self():\n    model, example_data = run_model_example(n_examples=1)\n    example = example_data[\n        len(example_data) - 1\n    ]  # batch object for the final example\n\n    layer_viz = [\n        visualize_layer(\n            model, layer, get_encoder, len(example[1]), example[1], example[1]\n        )\n        for layer in range(6)\n    ]\n    return alt.hconcat(\n        layer_viz[0]\n        # & layer_viz[1]\n        & layer_viz[2]\n        # & layer_viz[3]\n        & layer_viz[4]\n        # & layer_viz[5]\n    )\n\n\nshow_example(viz_encoder_self)
\n
Preparing Data ...\nLoading Trained Model ...\nChecking Model Outputs:\n\nExample 0 ========\n\nSource Text (Input)        : <s> Zwei Frauen in pinkfarbenen T-Shirts und <unk> unterhalten sich vor einem <unk> . </s>\nTarget Text (Ground Truth) : <s> Two women wearing pink T - shirts and blue jeans converse outside clothing store . </s>\nModel Output               : <s> Two women in pink shirts and face are talking in front of a <unk> . </s>
\n
\n\n
\n\n

Decoder Self Attention

\n
def viz_decoder_self():\n    model, example_data = run_model_example(n_examples=1)\n    example = example_data[len(example_data) - 1]\n\n    layer_viz = [\n        visualize_layer(\n            model,\n            layer,\n            get_decoder_self,\n            len(example[1]),\n            example[1],\n            example[1],\n        )\n        for layer in range(6)\n    ]\n    return alt.hconcat(\n        layer_viz[0]\n        & layer_viz[1]\n        & layer_viz[2]\n        & layer_viz[3]\n        & layer_viz[4]\n        & layer_viz[5]\n    )\n\n\nshow_example(viz_decoder_self)
\n
Preparing Data ...\nLoading Trained Model ...\nChecking Model Outputs:\n\nExample 0 ========\n\nSource Text (Input)        : <s> Eine Gruppe von Männern in Kostümen spielt Musik . </s>\nTarget Text (Ground Truth) : <s> A group of men in costume play music . </s>\nModel Output               : <s> A group of men in costumes playing music . </s>
\n
\n\n
\n\n

Decoder Src Attention

\n
def viz_decoder_src():\n    model, example_data = run_model_example(n_examples=1)\n    example = example_data[len(example_data) - 1]\n\n    layer_viz = [\n        visualize_layer(\n            model,\n            layer,\n            get_decoder_src,\n            max(len(example[1]), len(example[2])),\n            example[1],\n            example[2],\n        )\n        for layer in range(6)\n    ]\n    return alt.hconcat(\n        layer_viz[0]\n        & layer_viz[1]\n        & layer_viz[2]\n        & layer_viz[3]\n        & layer_viz[4]\n        & layer_viz[5]\n    )\n\n\nshow_example(viz_decoder_src)
\n
Preparing Data ...\nLoading Trained Model ...\nChecking Model Outputs:\n\nExample 0 ========\n\nSource Text (Input)        : <s> Ein kleiner Junge verwendet einen Bohrer , um ein Loch in ein Holzstück zu machen . </s>\nTarget Text (Ground Truth) : <s> A little boy using a drill to make a hole in a piece of wood . </s>\nModel Output               : <s> A little boy uses a machine to be working in a hole in a log . </s>
\n
\n\n
\n\n

Conclusion

\n

Hopefully this code is useful for future research. Please reach out if you have any issues.

\n

Cheers, Sasha Rush, Austin Huang, Suraj Subramanian, Jonathan Sum, Khalid Almubarak, Stella Biderman

\n\n\n" }, { "path": "docs/tufte.css", "content": "/* Import ET Book styles\n adapted from https://github.com/edwardtufte/et-book/blob/gh-pages/et-book.css */\n\n@charset \"UTF-8\";\n\n@font-face {\n font-family: \"et-book\";\n src: url(\"et-book/et-book-roman-line-figures/et-book-roman-line-figures.woff\") format(\"woff\");\n font-weight: normal;\n font-style: normal\n}\n\n@font-face {\n font-family: \"et-book\";\n src: url(\"et-book/et-book-display-italic-old-style-figures/et-book-display-italic-old-style-figures.woff\") format(\"woff\");\n font-weight: normal;\n font-style: italic\n}\n\n@font-face {\n font-family: \"et-book\";\n src: url(\"et-book/et-book-bold-line-figures/et-book-bold-line-figures.woff\") format(\"woff\");\n font-weight: bold;\n font-style: normal\n}\n\n@font-face {\n font-family: \"et-book-roman-old-style\";\n src: url(\"et-book/et-book-roman-old-style-figures/et-book-roman-old-style-figures.woff\") format(\"woff\");\n font-weight: normal;\n font-style: normal;\n}\n\n/* Tufte CSS styles */\nhtml { font-size: 15px; }\n\nbody { width: 58rem;\n margin-left: auto;\n margin-right: auto;\n padding: 0 2rem 8rem 2rem;\n font-family: et-book, Palatino, \"Palatino Linotype\", \"Palatino LT STD\", \"Book Antiqua\", Georgia, serif;\n background-color: white;\n color: #404444;\n max-width: 99%;\n box-sizing: border-box;\n counter-reset: sidenote-counter; }\n\nh1 { font-weight: 400;\n margin-top: 4rem;\n margin-bottom: 1.5rem;\n font-size: 3rem;\n line-height: 1; }\n\nh2 { \n font-weight: 400;\n margin-top: 2.1rem;\n margin-bottom: 0;\n font-size: 2rem;\n line-height: 1; }\n\nh3 { \n font-weight: 400;\n font-size: 1.4rem;\n margin-top: 2rem;\n margin-bottom: 0;\n line-height: 1; }\n\np.subtitle { font-style: italic;\n margin-top: 1rem;\n margin-bottom: 1rem;\n font-size: 1.8rem;\n display: block;\n line-height: 1; }\n\n.numeral { font-family: et-book-roman-old-style; }\n\n.danger { color: red; }\n\narticle { position: relative;\n padding: 5rem 0rem; }\n\nsection { padding-top: 1rem;\n padding-bottom: 1rem; }\n\np, ol, ul { font-size: 1.3rem; }\n\np { line-height: 2rem;\n margin-top: 1.4rem;\n margin-bottom: 1.4rem;\n padding-right: 0;\n vertical-align: baseline; }\n\n/* Chapter Epigraphs */\ndiv.epigraph { margin: 5em 0; }\n\ndiv.epigraph > blockquote { margin-top: 3em;\n margin-bottom: 3em; }\n\ndiv.epigraph > blockquote, div.epigraph > blockquote > p { font-style: italic; }\n\ndiv.epigraph > blockquote > footer { font-style: normal; }\n\ndiv.epigraph > blockquote > footer > cite { font-style: italic; }\n\n/* end chapter epigraphs styles */\n\nblockquote { border-left: 4px solid #cccccc;\n font-size: 1.4rem;\n font-style: normal;\n margin: 2rem 0;\n padding-left: 2rem;\n padding-right: 2rem; }\n\nblockquote p { padding-bottom: 6px; }\n\nblockquote footer { font-size: 1.1rem;\n text-align: right; }\n\nol, ul { padding-left: 2rem;\n -webkit-padding-start: 5%;\n -webkit-padding-end: 5%; }\n\nli { margin: 1rem 0; }\n\nli p { margin-bottom: 0.5rem;\n margin-top: 0.5rem; }\n\nfigure { padding: 0;\n border: 0;\n font-size: 100%;\n font: inherit;\n vertical-align: baseline;\n -webkit-margin-start: 0;\n -webkit-margin-end: 0;\n margin: 0 0 3em 0; }\n\nfigcaption { float: right;\n clear: right;\n margin-right: -48%;\n margin-top: 0;\n margin-bottom: 0;\n font-size: 1.1rem;\n line-height: 1.6;\n vertical-align: baseline;\n position: relative; }\n\nfigure.fullwidth figcaption { margin-right: 24%; }\n\n/* Links: replicate underline that clears descenders */\na:link, a:visited { color: inherit; }\n\na:link { text-decoration: none;\n background: -webkit-linear-gradient(#fffff8, #fffff8), -webkit-linear-gradient(#fffff8, #fffff8), -webkit-linear-gradient(#333, #333);\n background: linear-gradient(#fffff8, #fffff8), linear-gradient(#fffff8, #fffff8), linear-gradient(#333, #333);\n -webkit-background-size: 0.05em 1px, 0.05em 1px, 1px 1px;\n -moz-background-size: 0.05em 1px, 0.05em 1px, 1px 1px;\n background-size: 0.05em 1px, 0.05em 1px, 1px 1px;\n background-repeat: no-repeat, no-repeat, repeat-x;\n text-shadow: 0.03em 0 #fffff8, -0.03em 0 #fffff8, 0 0.03em #fffff8, 0 -0.03em #fffff8, 0.06em 0 #fffff8, -0.06em 0 #fffff8, 0.09em 0 #fffff8, -0.09em 0 #fffff8, 0.12em 0 #fffff8, -0.12em 0 #fffff8, 0.15em 0 #fffff8, -0.15em 0 #fffff8;\n background-position: 0% 93%, 100% 93%, 0% 93%; }\n\n@media screen and (-webkit-min-device-pixel-ratio: 0) { a:link { background-position-y: 87%, 87%, 87%; } }\n\na:link::selection { text-shadow: 0.03em 0 #b4d5fe, -0.03em 0 #b4d5fe, 0 0.03em #b4d5fe, 0 -0.03em #b4d5fe, 0.06em 0 #b4d5fe, -0.06em 0 #b4d5fe, 0.09em 0 #b4d5fe, -0.09em 0 #b4d5fe, 0.12em 0 #b4d5fe, -0.12em 0 #b4d5fe, 0.15em 0 #b4d5fe, -0.15em 0 #b4d5fe;\n background: #b4d5fe; }\n\na:link::-moz-selection { text-shadow: 0.03em 0 #b4d5fe, -0.03em 0 #b4d5fe, 0 0.03em #b4d5fe, 0 -0.03em #b4d5fe, 0.06em 0 #b4d5fe, -0.06em 0 #b4d5fe, 0.09em 0 #b4d5fe, -0.09em 0 #b4d5fe, 0.12em 0 #b4d5fe, -0.12em 0 #b4d5fe, 0.15em 0 #b4d5fe, -0.15em 0 #b4d5fe;\n background: #b4d5fe; }\n\n/* Hide the faux underline */\na img { vertical-align: bottom; }\n\n/* Sidenotes, margin notes, figures, captions */\nimg { }\n\n.sidenote, .marginnote { float: right;\n clear: right;\n margin-right: -60%;\n margin-top: 0;\n margin-bottom: 0;\n font-size: 1.1rem;\n line-height: 1.3;\n vertical-align: baseline;\n position: relative; }\n\n.table-caption { float:right;\n clear:right;\n margin-right: -60%;\n margin-top: 0;\n margin-bottom: 0;\n font-size: 1.0rem;\n line-height: 1.6; }\n\n.sidenote-number { counter-increment: sidenote-counter; }\n\n.sidenote-number:after, .sidenote:before { content: counter(sidenote-counter) \" \";\n font-family: et-book-roman-old-style;\n position: relative;\n vertical-align: baseline; }\n\n.sidenote-number:after { content: counter(sidenote-counter);\n font-size: 1rem;\n top: -0.5rem;\n left: 0.1rem; }\n\n.sidenote:before { content: counter(sidenote-counter) \" \";\n top: -0.5rem; }\n\np, footer, table, div.table-wrapper-small, div.supertable-wrapper > p, div.booktabs-wrapper { }\n\ndiv.fullwidth, table.fullwidth { }\n\ndiv.table-wrapper { overflow-x: scroll;\n font-family: \"Trebuchet MS\", \"Gill Sans\", \"Gill Sans MT\", sans-serif; }\n\n.sans { font-family: \"Gill Sans\", \"Gill Sans MT\", Calibri, sans-serif;\n letter-spacing: .03em; }\n\ncode, .code { font-family: Consolas, \"Liberation Mono\", Menlo, Courier, monospace;\n font-size: 1.0rem;\n line-height: 1.6;\n }\n\npre > code.hljs {\n background: hsl(0deg 0% 97%);\n padding: 30px\n \n}\n\nh1 .code, h2 .code, h3 .code { font-size: 0.80em; }\n\n.marginnote .code, .sidenote .code { font-size: 1rem; }\n\npre.code { padding-left: 2.5%;\n overflow-x: scroll; }\n\n.fullwidth { clear:both; }\n\nspan.newthought { font-variant: small-caps;\n font-size: 1.2em; }\n\ninput.margin-toggle { display: none; }\n\nlabel.sidenote-number { display: inline; }\n\nlabel.margin-toggle:not(.sidenote-number) { display: none; }\n\n\nimg {\n display: block;\n margin-left: auto;\n margin-right: auto;\n}\n\ndiv.vega-embed {\n display: block;\n margin-left: auto;\n margin-right: auto;\n}\n\ncanvas {\n display: block;\n margin-left: auto;\n margin-right: auto;\n\n}\n\n/* Tables */\n\ntable { border-collapse: collapse;\n font-family: \"Gill Sans\", \"Gill Sans MT\", Calibri, sans-serif;\n font-size: 1.125rem;\n margin: 2rem 0; }\n\nth { border-bottom: 2px solid #cccccc;\n font-weight: normal;\n padding: 0.4em 0.8em; }\n\ntd { padding: 0.4em 0.8em; }\n<\n" }, { "path": "requirements.txt", "content": "--find-links https://download.pytorch.org/whl/torch_stable.html\n\npandas==1.3.5\ntorch==1.11.0+cu113\ntorchdata==0.3.0\ntorchtext==0.12\nspacy==3.2\naltair==4.1\njupytext==1.13\nflake8\nblack\nGPUtil\nwandb\n" }, { "path": "the_annotated_transformer.py", "content": "# -*- coding: utf-8 -*-\n# ---\n# jupyter:\n# jupytext:\n# formats: ipynb,py:percent\n# text_representation:\n# extension: .py\n# format_name: percent\n# format_version: '1.3'\n# jupytext_version: 1.13.0\n# kernelspec:\n# display_name: Python 3 (ipykernel)\n# language: python\n# name: python3\n# ---\n# %% [markdown] id=\"SX7UC-8jTsp7\" tags=[]\n#\n#

The Annotated Transformer

\n#\n#\n#
\n#

Attention is All You Need\n#

\n#
\n#\n# \n#\n# * *v2022: Austin Huang, Suraj Subramanian, Jonathan Sum, Khalid Almubarak,\n# and Stella Biderman.*\n# * *[Original](https://nlp.seas.harvard.edu/2018/04/03/attention.html):\n# [Sasha Rush](http://rush-nlp.com/).*\n#\n#\n# The Transformer has been on a lot of\n# people's minds over the last year five years.\n# This post presents an annotated version of the paper in the\n# form of a line-by-line implementation. It reorders and deletes\n# some sections from the original paper and adds comments\n# throughout. This document itself is a working notebook, and should\n# be a completely usable implementation.\n# Code is available\n# [here](https://github.com/harvardnlp/annotated-transformer/).\n#\n\n\n# %% [markdown] id=\"RSntDwKhTsp-\"\n#

Table of Contents

\n# \n\n\n# %% [markdown] id=\"BhmOhn9lTsp8\"\n# # Prelims\n#\n# Skip\n\n# %% id=\"NwClcbH6Tsp8\"\n# # !pip install -r requirements.txt\n\n# %% id=\"NwClcbH6Tsp8\"\n# # Uncomment for colab\n# #\n# # !pip install -q torchdata==0.3.0 torchtext==0.12 spacy==3.2 altair GPUtil\n# # !python -m spacy download de_core_news_sm\n# # !python -m spacy download en_core_web_sm\n\n\n# %% id=\"v1-1MX6oTsp9\"\nimport os\nfrom os.path import exists\nimport torch\nimport torch.nn as nn\nfrom torch.nn.functional import log_softmax, pad\nimport math\nimport copy\nimport time\nfrom torch.optim.lr_scheduler import LambdaLR\nimport pandas as pd\nimport altair as alt\nfrom torchtext.data.functional import to_map_style_dataset\nfrom torch.utils.data import DataLoader\nfrom torchtext.vocab import build_vocab_from_iterator\nimport torchtext.datasets as datasets\nimport spacy\nimport GPUtil\nimport warnings\nfrom torch.utils.data.distributed import DistributedSampler\nimport torch.distributed as dist\nimport torch.multiprocessing as mp\nfrom torch.nn.parallel import DistributedDataParallel as DDP\n\n\n# Set to False to skip notebook execution (e.g. for debugging)\nwarnings.filterwarnings(\"ignore\")\nRUN_EXAMPLES = True\n\n\n# %%\n# Some convenience helper functions used throughout the notebook\n\n\ndef is_interactive_notebook():\n return __name__ == \"__main__\"\n\n\ndef show_example(fn, args=[]):\n if __name__ == \"__main__\" and RUN_EXAMPLES:\n return fn(*args)\n\n\ndef execute_example(fn, args=[]):\n if __name__ == \"__main__\" and RUN_EXAMPLES:\n fn(*args)\n\n\nclass DummyOptimizer(torch.optim.Optimizer):\n def __init__(self):\n self.param_groups = [{\"lr\": 0}]\n None\n\n def step(self):\n None\n\n def zero_grad(self, set_to_none=False):\n None\n\n\nclass DummyScheduler:\n def step(self):\n None\n\n\n# %% [markdown] id=\"jx49WRyfTsp-\"\n# > My comments are blockquoted. The main text is all from the paper itself.\n\n# %% [markdown] id=\"7phVeWghTsp_\"\n# # Background\n\n# %% [markdown] id=\"83ZDS91dTsqA\"\n#\n# The goal of reducing sequential computation also forms the\n# foundation of the Extended Neural GPU, ByteNet and ConvS2S, all of\n# which use convolutional neural networks as basic building block,\n# computing hidden representations in parallel for all input and\n# output positions. In these models, the number of operations required\n# to relate signals from two arbitrary input or output positions grows\n# in the distance between positions, linearly for ConvS2S and\n# logarithmically for ByteNet. This makes it more difficult to learn\n# dependencies between distant positions. In the Transformer this is\n# reduced to a constant number of operations, albeit at the cost of\n# reduced effective resolution due to averaging attention-weighted\n# positions, an effect we counteract with Multi-Head Attention.\n#\n# Self-attention, sometimes called intra-attention is an attention\n# mechanism relating different positions of a single sequence in order\n# to compute a representation of the sequence. Self-attention has been\n# used successfully in a variety of tasks including reading\n# comprehension, abstractive summarization, textual entailment and\n# learning task-independent sentence representations. End-to-end\n# memory networks are based on a recurrent attention mechanism instead\n# of sequencealigned recurrence and have been shown to perform well on\n# simple-language question answering and language modeling tasks.\n#\n# To the best of our knowledge, however, the Transformer is the first\n# transduction model relying entirely on self-attention to compute\n# representations of its input and output without using sequence\n# aligned RNNs or convolution.\n\n# %% [markdown]\n# # Part 1: Model Architecture\n\n# %% [markdown] id=\"pFrPajezTsqB\"\n# # Model Architecture\n\n# %% [markdown] id=\"ReuU_h-fTsqB\"\n#\n# Most competitive neural sequence transduction models have an\n# encoder-decoder structure\n# [(cite)](https://arxiv.org/abs/1409.0473). Here, the encoder maps an\n# input sequence of symbol representations $(x_1, ..., x_n)$ to a\n# sequence of continuous representations $\\mathbf{z} = (z_1, ...,\n# z_n)$. Given $\\mathbf{z}$, the decoder then generates an output\n# sequence $(y_1,...,y_m)$ of symbols one element at a time. At each\n# step the model is auto-regressive\n# [(cite)](https://arxiv.org/abs/1308.0850), consuming the previously\n# generated symbols as additional input when generating the next.\n\n# %% id=\"k0XGXhzRTsqB\"\nclass EncoderDecoder(nn.Module):\n \"\"\"\n A standard Encoder-Decoder architecture. Base for this and many\n other models.\n \"\"\"\n\n def __init__(self, encoder, decoder, src_embed, tgt_embed, generator):\n super(EncoderDecoder, self).__init__()\n self.encoder = encoder\n self.decoder = decoder\n self.src_embed = src_embed\n self.tgt_embed = tgt_embed\n self.generator = generator\n\n def forward(self, src, tgt, src_mask, tgt_mask):\n \"Take in and process masked src and target sequences.\"\n return self.decode(self.encode(src, src_mask), src_mask, tgt, tgt_mask)\n\n def encode(self, src, src_mask):\n return self.encoder(self.src_embed(src), src_mask)\n\n def decode(self, memory, src_mask, tgt, tgt_mask):\n return self.decoder(self.tgt_embed(tgt), memory, src_mask, tgt_mask)\n\n\n# %% id=\"NKGoH2RsTsqC\"\nclass Generator(nn.Module):\n \"Define standard linear + softmax generation step.\"\n\n def __init__(self, d_model, vocab):\n super(Generator, self).__init__()\n self.proj = nn.Linear(d_model, vocab)\n\n def forward(self, x):\n return log_softmax(self.proj(x), dim=-1)\n\n\n# %% [markdown] id=\"mOoEnF_jTsqC\"\n#\n# The Transformer follows this overall architecture using stacked\n# self-attention and point-wise, fully connected layers for both the\n# encoder and decoder, shown in the left and right halves of Figure 1,\n# respectively.\n\n# %% [markdown] id=\"oredWloYTsqC\"\n# ![](images/ModalNet-21.png)\n\n\n# %% [markdown] id=\"bh092NZBTsqD\"\n# ## Encoder and Decoder Stacks\n#\n# ### Encoder\n#\n# The encoder is composed of a stack of $N=6$ identical layers.\n\n# %% id=\"2gxTApUYTsqD\"\ndef clones(module, N):\n \"Produce N identical layers.\"\n return nn.ModuleList([copy.deepcopy(module) for _ in range(N)])\n\n\n# %% id=\"xqVTz9MkTsqD\"\nclass Encoder(nn.Module):\n \"Core encoder is a stack of N layers\"\n\n def __init__(self, layer, N):\n super(Encoder, self).__init__()\n self.layers = clones(layer, N)\n self.norm = LayerNorm(layer.size)\n\n def forward(self, x, mask):\n \"Pass the input (and mask) through each layer in turn.\"\n for layer in self.layers:\n x = layer(x, mask)\n return self.norm(x)\n\n\n# %% [markdown] id=\"GjAKgjGwTsqD\"\n#\n# We employ a residual connection\n# [(cite)](https://arxiv.org/abs/1512.03385) around each of the two\n# sub-layers, followed by layer normalization\n# [(cite)](https://arxiv.org/abs/1607.06450).\n\n# %% id=\"3jKa_prZTsqE\"\nclass LayerNorm(nn.Module):\n \"Construct a layernorm module (See citation for details).\"\n\n def __init__(self, features, eps=1e-6):\n super(LayerNorm, self).__init__()\n self.a_2 = nn.Parameter(torch.ones(features))\n self.b_2 = nn.Parameter(torch.zeros(features))\n self.eps = eps\n\n def forward(self, x):\n mean = x.mean(-1, keepdim=True)\n std = x.std(-1, keepdim=True)\n return self.a_2 * (x - mean) / (std + self.eps) + self.b_2\n\n\n# %% [markdown] id=\"nXSJ3QYmTsqE\"\n#\n# That is, the output of each sub-layer is $\\mathrm{LayerNorm}(x +\n# \\mathrm{Sublayer}(x))$, where $\\mathrm{Sublayer}(x)$ is the function\n# implemented by the sub-layer itself. We apply dropout\n# [(cite)](http://jmlr.org/papers/v15/srivastava14a.html) to the\n# output of each sub-layer, before it is added to the sub-layer input\n# and normalized.\n#\n# To facilitate these residual connections, all sub-layers in the\n# model, as well as the embedding layers, produce outputs of dimension\n# $d_{\\text{model}}=512$.\n\n# %% id=\"U1P7zI0eTsqE\"\nclass SublayerConnection(nn.Module):\n \"\"\"\n A residual connection followed by a layer norm.\n Note for code simplicity the norm is first as opposed to last.\n \"\"\"\n\n def __init__(self, size, dropout):\n super(SublayerConnection, self).__init__()\n self.norm = LayerNorm(size)\n self.dropout = nn.Dropout(dropout)\n\n def forward(self, x, sublayer):\n \"Apply residual connection to any sublayer with the same size.\"\n return x + self.dropout(sublayer(self.norm(x)))\n\n\n# %% [markdown] id=\"ML6oDlEqTsqE\"\n#\n# Each layer has two sub-layers. The first is a multi-head\n# self-attention mechanism, and the second is a simple, position-wise\n# fully connected feed-forward network.\n\n# %% id=\"qYkUFr6GTsqE\"\nclass EncoderLayer(nn.Module):\n \"Encoder is made up of self-attn and feed forward (defined below)\"\n\n def __init__(self, size, self_attn, feed_forward, dropout):\n super(EncoderLayer, self).__init__()\n self.self_attn = self_attn\n self.feed_forward = feed_forward\n self.sublayer = clones(SublayerConnection(size, dropout), 2)\n self.size = size\n\n def forward(self, x, mask):\n \"Follow Figure 1 (left) for connections.\"\n x = self.sublayer[0](x, lambda x: self.self_attn(x, x, x, mask))\n return self.sublayer[1](x, self.feed_forward)\n\n\n# %% [markdown] id=\"7ecOQIhkTsqF\"\n# ### Decoder\n#\n# The decoder is also composed of a stack of $N=6$ identical layers.\n#\n\n# %%\nclass Decoder(nn.Module):\n \"Generic N layer decoder with masking.\"\n\n def __init__(self, layer, N):\n super(Decoder, self).__init__()\n self.layers = clones(layer, N)\n self.norm = LayerNorm(layer.size)\n\n def forward(self, x, memory, src_mask, tgt_mask):\n for layer in self.layers:\n x = layer(x, memory, src_mask, tgt_mask)\n return self.norm(x)\n\n\n# %% [markdown] id=\"dXlCB12pTsqF\"\n#\n# In addition to the two sub-layers in each encoder layer, the decoder\n# inserts a third sub-layer, which performs multi-head attention over\n# the output of the encoder stack. Similar to the encoder, we employ\n# residual connections around each of the sub-layers, followed by\n# layer normalization.\n\n# %% id=\"M2hA1xFQTsqF\"\nclass DecoderLayer(nn.Module):\n \"Decoder is made of self-attn, src-attn, and feed forward (defined below)\"\n\n def __init__(self, size, self_attn, src_attn, feed_forward, dropout):\n super(DecoderLayer, self).__init__()\n self.size = size\n self.self_attn = self_attn\n self.src_attn = src_attn\n self.feed_forward = feed_forward\n self.sublayer = clones(SublayerConnection(size, dropout), 3)\n\n def forward(self, x, memory, src_mask, tgt_mask):\n \"Follow Figure 1 (right) for connections.\"\n m = memory\n x = self.sublayer[0](x, lambda x: self.self_attn(x, x, x, tgt_mask))\n x = self.sublayer[1](x, lambda x: self.src_attn(x, m, m, src_mask))\n return self.sublayer[2](x, self.feed_forward)\n\n\n# %% [markdown] id=\"FZz5rLl4TsqF\"\n#\n# We also modify the self-attention sub-layer in the decoder stack to\n# prevent positions from attending to subsequent positions. This\n# masking, combined with fact that the output embeddings are offset by\n# one position, ensures that the predictions for position $i$ can\n# depend only on the known outputs at positions less than $i$.\n\n# %% id=\"QN98O2l3TsqF\"\ndef subsequent_mask(size):\n \"Mask out subsequent positions.\"\n attn_shape = (1, size, size)\n subsequent_mask = torch.triu(torch.ones(attn_shape), diagonal=1).type(\n torch.uint8\n )\n return subsequent_mask == 0\n\n\n# %% [markdown] id=\"Vg_f_w-PTsqG\"\n#\n# > Below the attention mask shows the position each tgt word (row) is\n# > allowed to look at (column). Words are blocked for attending to\n# > future words during training.\n\n# %% id=\"ht_FtgYAokC4\"\ndef example_mask():\n LS_data = pd.concat(\n [\n pd.DataFrame(\n {\n \"Subsequent Mask\": subsequent_mask(20)[0][x, y].flatten(),\n \"Window\": y,\n \"Masking\": x,\n }\n )\n for y in range(20)\n for x in range(20)\n ]\n )\n\n return (\n alt.Chart(LS_data)\n .mark_rect()\n .properties(height=250, width=250)\n .encode(\n alt.X(\"Window:O\"),\n alt.Y(\"Masking:O\"),\n alt.Color(\"Subsequent Mask:Q\", scale=alt.Scale(scheme=\"viridis\")),\n )\n .interactive()\n )\n\n\nshow_example(example_mask)\n\n# %% [markdown] id=\"Qto_yg7BTsqG\"\n# ### Attention\n#\n# An attention function can be described as mapping a query and a set\n# of key-value pairs to an output, where the query, keys, values, and\n# output are all vectors. The output is computed as a weighted sum of\n# the values, where the weight assigned to each value is computed by a\n# compatibility function of the query with the corresponding key.\n#\n# We call our particular attention \"Scaled Dot-Product Attention\".\n# The input consists of queries and keys of dimension $d_k$, and\n# values of dimension $d_v$. We compute the dot products of the query\n# with all keys, divide each by $\\sqrt{d_k}$, and apply a softmax\n# function to obtain the weights on the values.\n#\n#\n#\n# ![](images/ModalNet-19.png)\n\n\n# %% [markdown] id=\"EYJLWk6cTsqG\"\n#\n# In practice, we compute the attention function on a set of queries\n# simultaneously, packed together into a matrix $Q$. The keys and\n# values are also packed together into matrices $K$ and $V$. We\n# compute the matrix of outputs as:\n#\n# $$\n# \\mathrm{Attention}(Q, K, V) = \\mathrm{softmax}(\\frac{QK^T}{\\sqrt{d_k}})V\n# $$\n\n# %% id=\"qsoVxS5yTsqG\"\ndef attention(query, key, value, mask=None, dropout=None):\n \"Compute 'Scaled Dot Product Attention'\"\n d_k = query.size(-1)\n scores = torch.matmul(query, key.transpose(-2, -1)) / math.sqrt(d_k)\n if mask is not None:\n scores = scores.masked_fill(mask == 0, -1e9)\n p_attn = scores.softmax(dim=-1)\n if dropout is not None:\n p_attn = dropout(p_attn)\n return torch.matmul(p_attn, value), p_attn\n\n\n# %% [markdown] id=\"jUkpwu8kTsqG\"\n#\n# The two most commonly used attention functions are additive\n# attention [(cite)](https://arxiv.org/abs/1409.0473), and dot-product\n# (multiplicative) attention. Dot-product attention is identical to\n# our algorithm, except for the scaling factor of\n# $\\frac{1}{\\sqrt{d_k}}$. Additive attention computes the\n# compatibility function using a feed-forward network with a single\n# hidden layer. While the two are similar in theoretical complexity,\n# dot-product attention is much faster and more space-efficient in\n# practice, since it can be implemented using highly optimized matrix\n# multiplication code.\n#\n#\n# While for small values of $d_k$ the two mechanisms perform\n# similarly, additive attention outperforms dot product attention\n# without scaling for larger values of $d_k$\n# [(cite)](https://arxiv.org/abs/1703.03906). We suspect that for\n# large values of $d_k$, the dot products grow large in magnitude,\n# pushing the softmax function into regions where it has extremely\n# small gradients (To illustrate why the dot products get large,\n# assume that the components of $q$ and $k$ are independent random\n# variables with mean $0$ and variance $1$. Then their dot product,\n# $q \\cdot k = \\sum_{i=1}^{d_k} q_ik_i$, has mean $0$ and variance\n# $d_k$.). To counteract this effect, we scale the dot products by\n# $\\frac{1}{\\sqrt{d_k}}$.\n#\n#\n\n# %% [markdown] id=\"bS1FszhVTsqG\"\n# ![](images/ModalNet-20.png)\n\n\n# %% [markdown] id=\"TNtVyZ-pTsqH\"\n#\n# Multi-head attention allows the model to jointly attend to\n# information from different representation subspaces at different\n# positions. With a single attention head, averaging inhibits this.\n#\n# $$\n# \\mathrm{MultiHead}(Q, K, V) =\n# \\mathrm{Concat}(\\mathrm{head_1}, ..., \\mathrm{head_h})W^O \\\\\n# \\text{where}~\\mathrm{head_i} = \\mathrm{Attention}(QW^Q_i, KW^K_i, VW^V_i)\n# $$\n#\n# Where the projections are parameter matrices $W^Q_i \\in\n# \\mathbb{R}^{d_{\\text{model}} \\times d_k}$, $W^K_i \\in\n# \\mathbb{R}^{d_{\\text{model}} \\times d_k}$, $W^V_i \\in\n# \\mathbb{R}^{d_{\\text{model}} \\times d_v}$ and $W^O \\in\n# \\mathbb{R}^{hd_v \\times d_{\\text{model}}}$.\n#\n# In this work we employ $h=8$ parallel attention layers, or\n# heads. For each of these we use $d_k=d_v=d_{\\text{model}}/h=64$. Due\n# to the reduced dimension of each head, the total computational cost\n# is similar to that of single-head attention with full\n# dimensionality.\n\n# %% id=\"D2LBMKCQTsqH\"\nclass MultiHeadedAttention(nn.Module):\n def __init__(self, h, d_model, dropout=0.1):\n \"Take in model size and number of heads.\"\n super(MultiHeadedAttention, self).__init__()\n assert d_model % h == 0\n # We assume d_v always equals d_k\n self.d_k = d_model // h\n self.h = h\n self.linears = clones(nn.Linear(d_model, d_model), 4)\n self.attn = None\n self.dropout = nn.Dropout(p=dropout)\n\n def forward(self, query, key, value, mask=None):\n \"Implements Figure 2\"\n if mask is not None:\n # Same mask applied to all h heads.\n mask = mask.unsqueeze(1)\n nbatches = query.size(0)\n\n # 1) Do all the linear projections in batch from d_model => h x d_k\n query, key, value = [\n lin(x).view(nbatches, -1, self.h, self.d_k).transpose(1, 2)\n for lin, x in zip(self.linears, (query, key, value))\n ]\n\n # 2) Apply attention on all the projected vectors in batch.\n x, self.attn = attention(\n query, key, value, mask=mask, dropout=self.dropout\n )\n\n # 3) \"Concat\" using a view and apply a final linear.\n x = (\n x.transpose(1, 2)\n .contiguous()\n .view(nbatches, -1, self.h * self.d_k)\n )\n del query\n del key\n del value\n return self.linears[-1](x)\n\n\n# %% [markdown] id=\"EDRba3J3TsqH\"\n# ### Applications of Attention in our Model\n#\n# The Transformer uses multi-head attention in three different ways:\n# 1) In \"encoder-decoder attention\" layers, the queries come from the\n# previous decoder layer, and the memory keys and values come from the\n# output of the encoder. This allows every position in the decoder to\n# attend over all positions in the input sequence. This mimics the\n# typical encoder-decoder attention mechanisms in sequence-to-sequence\n# models such as [(cite)](https://arxiv.org/abs/1609.08144).\n#\n#\n# 2) The encoder contains self-attention layers. In a self-attention\n# layer all of the keys, values and queries come from the same place,\n# in this case, the output of the previous layer in the encoder. Each\n# position in the encoder can attend to all positions in the previous\n# layer of the encoder.\n#\n#\n# 3) Similarly, self-attention layers in the decoder allow each\n# position in the decoder to attend to all positions in the decoder up\n# to and including that position. We need to prevent leftward\n# information flow in the decoder to preserve the auto-regressive\n# property. We implement this inside of scaled dot-product attention\n# by masking out (setting to $-\\infty$) all values in the input of the\n# softmax which correspond to illegal connections.\n\n# %% [markdown] id=\"M-en97_GTsqH\"\n# ## Position-wise Feed-Forward Networks\n#\n# In addition to attention sub-layers, each of the layers in our\n# encoder and decoder contains a fully connected feed-forward network,\n# which is applied to each position separately and identically. This\n# consists of two linear transformations with a ReLU activation in\n# between.\n#\n# $$\\mathrm{FFN}(x)=\\max(0, xW_1 + b_1) W_2 + b_2$$\n#\n# While the linear transformations are the same across different\n# positions, they use different parameters from layer to\n# layer. Another way of describing this is as two convolutions with\n# kernel size 1. The dimensionality of input and output is\n# $d_{\\text{model}}=512$, and the inner-layer has dimensionality\n# $d_{ff}=2048$.\n\n# %% id=\"6HHCemCxTsqH\"\nclass PositionwiseFeedForward(nn.Module):\n \"Implements FFN equation.\"\n\n def __init__(self, d_model, d_ff, dropout=0.1):\n super(PositionwiseFeedForward, self).__init__()\n self.w_1 = nn.Linear(d_model, d_ff)\n self.w_2 = nn.Linear(d_ff, d_model)\n self.dropout = nn.Dropout(dropout)\n\n def forward(self, x):\n return self.w_2(self.dropout(self.w_1(x).relu()))\n\n\n# %% [markdown] id=\"dR1YM520TsqH\"\n# ## Embeddings and Softmax\n#\n# Similarly to other sequence transduction models, we use learned\n# embeddings to convert the input tokens and output tokens to vectors\n# of dimension $d_{\\text{model}}$. We also use the usual learned\n# linear transformation and softmax function to convert the decoder\n# output to predicted next-token probabilities. In our model, we\n# share the same weight matrix between the two embedding layers and\n# the pre-softmax linear transformation, similar to\n# [(cite)](https://arxiv.org/abs/1608.05859). In the embedding layers,\n# we multiply those weights by $\\sqrt{d_{\\text{model}}}$.\n\n# %% id=\"pyrChq9qTsqH\"\nclass Embeddings(nn.Module):\n def __init__(self, d_model, vocab):\n super(Embeddings, self).__init__()\n self.lut = nn.Embedding(vocab, d_model)\n self.d_model = d_model\n\n def forward(self, x):\n return self.lut(x) * math.sqrt(self.d_model)\n\n\n# %% [markdown] id=\"vOkdui-cTsqH\"\n# ## Positional Encoding\n#\n# Since our model contains no recurrence and no convolution, in order\n# for the model to make use of the order of the sequence, we must\n# inject some information about the relative or absolute position of\n# the tokens in the sequence. To this end, we add \"positional\n# encodings\" to the input embeddings at the bottoms of the encoder and\n# decoder stacks. The positional encodings have the same dimension\n# $d_{\\text{model}}$ as the embeddings, so that the two can be summed.\n# There are many choices of positional encodings, learned and fixed\n# [(cite)](https://arxiv.org/pdf/1705.03122.pdf).\n#\n# In this work, we use sine and cosine functions of different frequencies:\n#\n# $$PE_{(pos,2i)} = \\sin(pos / 10000^{2i/d_{\\text{model}}})$$\n#\n# $$PE_{(pos,2i+1)} = \\cos(pos / 10000^{2i/d_{\\text{model}}})$$\n#\n# where $pos$ is the position and $i$ is the dimension. That is, each\n# dimension of the positional encoding corresponds to a sinusoid. The\n# wavelengths form a geometric progression from $2\\pi$ to $10000 \\cdot\n# 2\\pi$. We chose this function because we hypothesized it would\n# allow the model to easily learn to attend by relative positions,\n# since for any fixed offset $k$, $PE_{pos+k}$ can be represented as a\n# linear function of $PE_{pos}$.\n#\n# In addition, we apply dropout to the sums of the embeddings and the\n# positional encodings in both the encoder and decoder stacks. For\n# the base model, we use a rate of $P_{drop}=0.1$.\n#\n#\n\n# %% id=\"zaHGD4yJTsqH\"\nclass PositionalEncoding(nn.Module):\n \"Implement the PE function.\"\n\n def __init__(self, d_model, dropout, max_len=5000):\n super(PositionalEncoding, self).__init__()\n self.dropout = nn.Dropout(p=dropout)\n\n # Compute the positional encodings once in log space.\n pe = torch.zeros(max_len, d_model)\n position = torch.arange(0, max_len).unsqueeze(1)\n div_term = torch.exp(\n torch.arange(0, d_model, 2) * -(math.log(10000.0) / d_model)\n )\n pe[:, 0::2] = torch.sin(position * div_term)\n pe[:, 1::2] = torch.cos(position * div_term)\n pe = pe.unsqueeze(0)\n self.register_buffer(\"pe\", pe)\n\n def forward(self, x):\n x = x + self.pe[:, : x.size(1)].requires_grad_(False)\n return self.dropout(x)\n\n\n# %% [markdown] id=\"EfHacTJLTsqH\"\n#\n# > Below the positional encoding will add in a sine wave based on\n# > position. The frequency and offset of the wave is different for\n# > each dimension.\n\n# %% id=\"rnvHk_1QokC6\" type=\"example\"\ndef example_positional():\n pe = PositionalEncoding(20, 0)\n y = pe.forward(torch.zeros(1, 100, 20))\n\n data = pd.concat(\n [\n pd.DataFrame(\n {\n \"embedding\": y[0, :, dim],\n \"dimension\": dim,\n \"position\": list(range(100)),\n }\n )\n for dim in [4, 5, 6, 7]\n ]\n )\n\n return (\n alt.Chart(data)\n .mark_line()\n .properties(width=800)\n .encode(x=\"position\", y=\"embedding\", color=\"dimension:N\")\n .interactive()\n )\n\n\nshow_example(example_positional)\n\n\n# %% [markdown] id=\"g8rZNCrzTsqI\"\n#\n# We also experimented with using learned positional embeddings\n# [(cite)](https://arxiv.org/pdf/1705.03122.pdf) instead, and found\n# that the two versions produced nearly identical results. We chose\n# the sinusoidal version because it may allow the model to extrapolate\n# to sequence lengths longer than the ones encountered during\n# training.\n\n# %% [markdown] id=\"iwNKCzlyTsqI\"\n# ## Full Model\n#\n# > Here we define a function from hyperparameters to a full model.\n\n# %% id=\"mPe1ES0UTsqI\"\ndef make_model(\n src_vocab, tgt_vocab, N=6, d_model=512, d_ff=2048, h=8, dropout=0.1\n):\n \"Helper: Construct a model from hyperparameters.\"\n c = copy.deepcopy\n attn = MultiHeadedAttention(h, d_model)\n ff = PositionwiseFeedForward(d_model, d_ff, dropout)\n position = PositionalEncoding(d_model, dropout)\n model = EncoderDecoder(\n Encoder(EncoderLayer(d_model, c(attn), c(ff), dropout), N),\n Decoder(DecoderLayer(d_model, c(attn), c(attn), c(ff), dropout), N),\n nn.Sequential(Embeddings(d_model, src_vocab), c(position)),\n nn.Sequential(Embeddings(d_model, tgt_vocab), c(position)),\n Generator(d_model, tgt_vocab),\n )\n\n # This was important from their code.\n # Initialize parameters with Glorot / fan_avg.\n for p in model.parameters():\n if p.dim() > 1:\n nn.init.xavier_uniform_(p)\n return model\n\n\n# %% [markdown]\n# ## Inference:\n#\n# > Here we make a forward step to generate a prediction of the\n# model. We try to use our transformer to memorize the input. As you\n# will see the output is randomly generated due to the fact that the\n# model is not trained yet. In the next tutorial we will build the\n# training function and try to train our model to memorize the numbers\n# from 1 to 10.\n\n# %%\ndef inference_test():\n test_model = make_model(11, 11, 2)\n test_model.eval()\n src = torch.LongTensor([[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]])\n src_mask = torch.ones(1, 1, 10)\n\n memory = test_model.encode(src, src_mask)\n ys = torch.zeros(1, 1).type_as(src)\n\n for i in range(9):\n out = test_model.decode(\n memory, src_mask, ys, subsequent_mask(ys.size(1)).type_as(src.data)\n )\n prob = test_model.generator(out[:, -1])\n _, next_word = torch.max(prob, dim=1)\n next_word = next_word.data[0]\n ys = torch.cat(\n [ys, torch.empty(1, 1).type_as(src.data).fill_(next_word)], dim=1\n )\n\n print(\"Example Untrained Model Prediction:\", ys)\n\n\ndef run_tests():\n for _ in range(10):\n inference_test()\n\n\nshow_example(run_tests)\n\n\n# %% [markdown]\n# # Part 2: Model Training\n\n# %% [markdown] id=\"05s6oT9fTsqI\"\n# # Training\n#\n# This section describes the training regime for our models.\n\n# %% [markdown] id=\"fTxlofs4TsqI\"\n#\n# > We stop for a quick interlude to introduce some of the tools\n# > needed to train a standard encoder decoder model. First we define a\n# > batch object that holds the src and target sentences for training,\n# > as well as constructing the masks.\n\n# %% [markdown] id=\"G7SkCenXTsqI\"\n# ## Batches and Masking\n\n# %%\nclass Batch:\n \"\"\"Object for holding a batch of data with mask during training.\"\"\"\n\n def __init__(self, src, tgt=None, pad=2): # 2 = \n self.src = src\n self.src_mask = (src != pad).unsqueeze(-2)\n if tgt is not None:\n self.tgt = tgt[:, :-1]\n self.tgt_y = tgt[:, 1:]\n self.tgt_mask = self.make_std_mask(self.tgt, pad)\n self.ntokens = (self.tgt_y != pad).data.sum()\n\n @staticmethod\n def make_std_mask(tgt, pad):\n \"Create a mask to hide padding and future words.\"\n tgt_mask = (tgt != pad).unsqueeze(-2)\n tgt_mask = tgt_mask & subsequent_mask(tgt.size(-1)).type_as(\n tgt_mask.data\n )\n return tgt_mask\n\n\n# %% [markdown] id=\"cKkw5GjLTsqI\"\n#\n# > Next we create a generic training and scoring function to keep\n# > track of loss. We pass in a generic loss compute function that\n# > also handles parameter updates.\n\n# %% [markdown] id=\"Q8zzeUc0TsqJ\"\n# ## Training Loop\n\n# %%\nclass TrainState:\n \"\"\"Track number of steps, examples, and tokens processed\"\"\"\n\n step: int = 0 # Steps in the current epoch\n accum_step: int = 0 # Number of gradient accumulation steps\n samples: int = 0 # total # of examples used\n tokens: int = 0 # total # of tokens processed\n\n\n# %% id=\"2HAZD3hiTsqJ\"\ndef run_epoch(\n data_iter,\n model,\n loss_compute,\n optimizer,\n scheduler,\n mode=\"train\",\n accum_iter=1,\n train_state=TrainState(),\n):\n \"\"\"Train a single epoch\"\"\"\n start = time.time()\n total_tokens = 0\n total_loss = 0\n tokens = 0\n n_accum = 0\n for i, batch in enumerate(data_iter):\n out = model.forward(\n batch.src, batch.tgt, batch.src_mask, batch.tgt_mask\n )\n loss, loss_node = loss_compute(out, batch.tgt_y, batch.ntokens)\n # loss_node = loss_node / accum_iter\n if mode == \"train\" or mode == \"train+log\":\n loss_node.backward()\n train_state.step += 1\n train_state.samples += batch.src.shape[0]\n train_state.tokens += batch.ntokens\n if i % accum_iter == 0:\n optimizer.step()\n optimizer.zero_grad(set_to_none=True)\n n_accum += 1\n train_state.accum_step += 1\n scheduler.step()\n\n total_loss += loss\n total_tokens += batch.ntokens\n tokens += batch.ntokens\n if i % 40 == 1 and (mode == \"train\" or mode == \"train+log\"):\n lr = optimizer.param_groups[0][\"lr\"]\n elapsed = time.time() - start\n print(\n (\n \"Epoch Step: %6d | Accumulation Step: %3d | Loss: %6.2f \"\n + \"| Tokens / Sec: %7.1f | Learning Rate: %6.1e\"\n )\n % (i, n_accum, loss / batch.ntokens, tokens / elapsed, lr)\n )\n start = time.time()\n tokens = 0\n del loss\n del loss_node\n return total_loss / total_tokens, train_state\n\n\n# %% [markdown] id=\"aB1IF0foTsqJ\"\n# ## Training Data and Batching\n#\n# We trained on the standard WMT 2014 English-German dataset\n# consisting of about 4.5 million sentence pairs. Sentences were\n# encoded using byte-pair encoding, which has a shared source-target\n# vocabulary of about 37000 tokens. For English-French, we used the\n# significantly larger WMT 2014 English-French dataset consisting of\n# 36M sentences and split tokens into a 32000 word-piece vocabulary.\n#\n#\n# Sentence pairs were batched together by approximate sequence length.\n# Each training batch contained a set of sentence pairs containing\n# approximately 25000 source tokens and 25000 target tokens.\n\n# %% [markdown] id=\"F1mTQatiTsqJ\" jp-MarkdownHeadingCollapsed=true tags=[]\n# ## Hardware and Schedule\n#\n# We trained our models on one machine with 8 NVIDIA P100 GPUs. For\n# our base models using the hyperparameters described throughout the\n# paper, each training step took about 0.4 seconds. We trained the\n# base models for a total of 100,000 steps or 12 hours. For our big\n# models, step time was 1.0 seconds. The big models were trained for\n# 300,000 steps (3.5 days).\n\n# %% [markdown] id=\"-utZeuGcTsqJ\"\n# ## Optimizer\n#\n# We used the Adam optimizer [(cite)](https://arxiv.org/abs/1412.6980)\n# with $\\beta_1=0.9$, $\\beta_2=0.98$ and $\\epsilon=10^{-9}$. We\n# varied the learning rate over the course of training, according to\n# the formula:\n#\n# $$\n# lrate = d_{\\text{model}}^{-0.5} \\cdot\n# \\min({step\\_num}^{-0.5},\n# {step\\_num} \\cdot {warmup\\_steps}^{-1.5})\n# $$\n#\n# This corresponds to increasing the learning rate linearly for the\n# first $warmup\\_steps$ training steps, and decreasing it thereafter\n# proportionally to the inverse square root of the step number. We\n# used $warmup\\_steps=4000$.\n\n# %% [markdown] id=\"39FbYnt-TsqJ\"\n#\n# > Note: This part is very important. Need to train with this setup\n# > of the model.\n\n# %% [markdown] id=\"hlbojFkjTsqJ\"\n#\n# > Example of the curves of this model for different model sizes and\n# > for optimization hyperparameters.\n\n# %% id=\"zUz3PdAnVg4o\"\ndef rate(step, model_size, factor, warmup):\n \"\"\"\n we have to default the step to 1 for LambdaLR function\n to avoid zero raising to negative power.\n \"\"\"\n if step == 0:\n step = 1\n return factor * (\n model_size ** (-0.5) * min(step ** (-0.5), step * warmup ** (-1.5))\n )\n\n\n# %% id=\"l1bnrlnSV8J5\" tags=[]\ndef example_learning_schedule():\n opts = [\n [512, 1, 4000], # example 1\n [512, 1, 8000], # example 2\n [256, 1, 4000], # example 3\n ]\n\n dummy_model = torch.nn.Linear(1, 1)\n learning_rates = []\n\n # we have 3 examples in opts list.\n for idx, example in enumerate(opts):\n # run 20000 epoch for each example\n optimizer = torch.optim.Adam(\n dummy_model.parameters(), lr=1, betas=(0.9, 0.98), eps=1e-9\n )\n lr_scheduler = LambdaLR(\n optimizer=optimizer, lr_lambda=lambda step: rate(step, *example)\n )\n tmp = []\n # take 20K dummy training steps, save the learning rate at each step\n for step in range(20000):\n tmp.append(optimizer.param_groups[0][\"lr\"])\n optimizer.step()\n lr_scheduler.step()\n learning_rates.append(tmp)\n\n learning_rates = torch.tensor(learning_rates)\n\n # Enable altair to handle more than 5000 rows\n alt.data_transformers.disable_max_rows()\n\n opts_data = pd.concat(\n [\n pd.DataFrame(\n {\n \"Learning Rate\": learning_rates[warmup_idx, :],\n \"model_size:warmup\": [\"512:4000\", \"512:8000\", \"256:4000\"][\n warmup_idx\n ],\n \"step\": range(20000),\n }\n )\n for warmup_idx in [0, 1, 2]\n ]\n )\n\n return (\n alt.Chart(opts_data)\n .mark_line()\n .properties(width=600)\n .encode(x=\"step\", y=\"Learning Rate\", color=\"model_size:warmup:N\")\n .interactive()\n )\n\n\nexample_learning_schedule()\n\n\n# %% [markdown] id=\"7T1uD15VTsqK\"\n# ## Regularization\n#\n# ### Label Smoothing\n#\n# During training, we employed label smoothing of value\n# $\\epsilon_{ls}=0.1$ [(cite)](https://arxiv.org/abs/1512.00567).\n# This hurts perplexity, as the model learns to be more unsure, but\n# improves accuracy and BLEU score.\n\n# %% [markdown] id=\"kNoAVD8bTsqK\"\n#\n# > We implement label smoothing using the KL div loss. Instead of\n# > using a one-hot target distribution, we create a distribution that\n# > has `confidence` of the correct word and the rest of the\n# > `smoothing` mass distributed throughout the vocabulary.\n\n# %% id=\"shU2GyiETsqK\"\nclass LabelSmoothing(nn.Module):\n \"Implement label smoothing.\"\n\n def __init__(self, size, padding_idx, smoothing=0.0):\n super(LabelSmoothing, self).__init__()\n self.criterion = nn.KLDivLoss(reduction=\"sum\")\n self.padding_idx = padding_idx\n self.confidence = 1.0 - smoothing\n self.smoothing = smoothing\n self.size = size\n self.true_dist = None\n\n def forward(self, x, target):\n assert x.size(1) == self.size\n true_dist = x.data.clone()\n true_dist.fill_(self.smoothing / (self.size - 2))\n true_dist.scatter_(1, target.data.unsqueeze(1), self.confidence)\n true_dist[:, self.padding_idx] = 0\n mask = torch.nonzero(target.data == self.padding_idx)\n if mask.dim() > 0:\n true_dist.index_fill_(0, mask.squeeze(), 0.0)\n self.true_dist = true_dist\n return self.criterion(x, true_dist.clone().detach())\n\n\n# %% [markdown] id=\"jCxUrlUyTsqK\"\n#\n# > Here we can see an example of how the mass is distributed to the\n# > words based on confidence.\n\n# %% id=\"EZtKaaQNTsqK\"\n# Example of label smoothing.\n\n\ndef example_label_smoothing():\n crit = LabelSmoothing(5, 0, 0.4)\n predict = torch.FloatTensor(\n [\n [0, 0.2, 0.7, 0.1, 0],\n [0, 0.2, 0.7, 0.1, 0],\n [0, 0.2, 0.7, 0.1, 0],\n [0, 0.2, 0.7, 0.1, 0],\n [0, 0.2, 0.7, 0.1, 0],\n ]\n )\n crit(x=predict.log(), target=torch.LongTensor([2, 1, 0, 3, 3]))\n LS_data = pd.concat(\n [\n pd.DataFrame(\n {\n \"target distribution\": crit.true_dist[x, y].flatten(),\n \"columns\": y,\n \"rows\": x,\n }\n )\n for y in range(5)\n for x in range(5)\n ]\n )\n\n return (\n alt.Chart(LS_data)\n .mark_rect(color=\"Blue\", opacity=1)\n .properties(height=200, width=200)\n .encode(\n alt.X(\"columns:O\", title=None),\n alt.Y(\"rows:O\", title=None),\n alt.Color(\n \"target distribution:Q\", scale=alt.Scale(scheme=\"viridis\")\n ),\n )\n .interactive()\n )\n\n\nshow_example(example_label_smoothing)\n\n\n# %% [markdown] id=\"CGM8J1veTsqK\"\n#\n# > Label smoothing actually starts to penalize the model if it gets\n# > very confident about a given choice.\n\n# %% id=\"78EHzLP7TsqK\"\n\n\ndef loss(x, crit):\n d = x + 3 * 1\n predict = torch.FloatTensor([[0, x / d, 1 / d, 1 / d, 1 / d]])\n return crit(predict.log(), torch.LongTensor([1])).data\n\n\ndef penalization_visualization():\n crit = LabelSmoothing(5, 0, 0.1)\n loss_data = pd.DataFrame(\n {\n \"Loss\": [loss(x, crit) for x in range(1, 100)],\n \"Steps\": list(range(99)),\n }\n ).astype(\"float\")\n\n return (\n alt.Chart(loss_data)\n .mark_line()\n .properties(width=350)\n .encode(\n x=\"Steps\",\n y=\"Loss\",\n )\n .interactive()\n )\n\n\nshow_example(penalization_visualization)\n\n\n# %% [markdown] id=\"67lUqeLXTsqK\"\n# # A First Example\n#\n# > We can begin by trying out a simple copy-task. Given a random set\n# > of input symbols from a small vocabulary, the goal is to generate\n# > back those same symbols.\n\n# %% [markdown] id=\"jJa-89_pTsqK\"\n# ## Synthetic Data\n\n# %% id=\"g1aTxeqqTsqK\"\ndef data_gen(V, batch_size, nbatches):\n \"Generate random data for a src-tgt copy task.\"\n for i in range(nbatches):\n data = torch.randint(1, V, size=(batch_size, 10))\n data[:, 0] = 1\n src = data.requires_grad_(False).clone().detach()\n tgt = data.requires_grad_(False).clone().detach()\n yield Batch(src, tgt, 0)\n\n\n# %% [markdown] id=\"XTXwD9hUTsqK\"\n# ## Loss Computation\n\n# %% id=\"3J8EJm87TsqK\"\nclass SimpleLossCompute:\n \"A simple loss compute and train function.\"\n\n def __init__(self, generator, criterion):\n self.generator = generator\n self.criterion = criterion\n\n def __call__(self, x, y, norm):\n x = self.generator(x)\n sloss = (\n self.criterion(\n x.contiguous().view(-1, x.size(-1)), y.contiguous().view(-1)\n )\n / norm\n )\n return sloss.data * norm, sloss\n\n\n# %% [markdown] id=\"eDAI7ELUTsqL\"\n# ## Greedy Decoding\n\n# %% [markdown] id=\"LFkWakplTsqL\" tags=[]\n# > This code predicts a translation using greedy decoding for simplicity.\n# %% id=\"N2UOpnT3bIyU\"\ndef greedy_decode(model, src, src_mask, max_len, start_symbol):\n memory = model.encode(src, src_mask)\n ys = torch.zeros(1, 1).fill_(start_symbol).type_as(src.data)\n for i in range(max_len - 1):\n out = model.decode(\n memory, src_mask, ys, subsequent_mask(ys.size(1)).type_as(src.data)\n )\n prob = model.generator(out[:, -1])\n _, next_word = torch.max(prob, dim=1)\n next_word = next_word.data[0]\n ys = torch.cat(\n [ys, torch.zeros(1, 1).type_as(src.data).fill_(next_word)], dim=1\n )\n return ys\n\n\n# %% id=\"qgIZ2yEtdYwe\" tags=[]\n# Train the simple copy task.\n\n\ndef example_simple_model():\n V = 11\n criterion = LabelSmoothing(size=V, padding_idx=0, smoothing=0.0)\n model = make_model(V, V, N=2)\n\n optimizer = torch.optim.Adam(\n model.parameters(), lr=0.5, betas=(0.9, 0.98), eps=1e-9\n )\n lr_scheduler = LambdaLR(\n optimizer=optimizer,\n lr_lambda=lambda step: rate(\n step, model_size=model.src_embed[0].d_model, factor=1.0, warmup=400\n ),\n )\n\n batch_size = 80\n for epoch in range(20):\n model.train()\n run_epoch(\n data_gen(V, batch_size, 20),\n model,\n SimpleLossCompute(model.generator, criterion),\n optimizer,\n lr_scheduler,\n mode=\"train\",\n )\n model.eval()\n run_epoch(\n data_gen(V, batch_size, 5),\n model,\n SimpleLossCompute(model.generator, criterion),\n DummyOptimizer(),\n DummyScheduler(),\n mode=\"eval\",\n )[0]\n\n model.eval()\n src = torch.LongTensor([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]])\n max_len = src.shape[1]\n src_mask = torch.ones(1, 1, max_len)\n print(greedy_decode(model, src, src_mask, max_len=max_len, start_symbol=0))\n\n\n# execute_example(example_simple_model)\n\n\n# %% [markdown] id=\"OpuQv2GsTsqL\"\n# # Part 3: A Real World Example\n#\n# > Now we consider a real-world example using the Multi30k\n# > German-English Translation task. This task is much smaller than\n# > the WMT task considered in the paper, but it illustrates the whole\n# > system. We also show how to use multi-gpu processing to make it\n# > really fast.\n\n# %% [markdown] id=\"8y9dpfolTsqL\" tags=[]\n# ## Data Loading\n#\n# > We will load the dataset using torchtext and spacy for\n# > tokenization.\n\n# %%\n# Load spacy tokenizer models, download them if they haven't been\n# downloaded already\n\n\ndef load_tokenizers():\n\n try:\n spacy_de = spacy.load(\"de_core_news_sm\")\n except IOError:\n os.system(\"python -m spacy download de_core_news_sm\")\n spacy_de = spacy.load(\"de_core_news_sm\")\n\n try:\n spacy_en = spacy.load(\"en_core_web_sm\")\n except IOError:\n os.system(\"python -m spacy download en_core_web_sm\")\n spacy_en = spacy.load(\"en_core_web_sm\")\n\n return spacy_de, spacy_en\n\n\n# %% id=\"t4BszXXJTsqL\" tags=[]\ndef tokenize(text, tokenizer):\n return [tok.text for tok in tokenizer.tokenizer(text)]\n\n\ndef yield_tokens(data_iter, tokenizer, index):\n for from_to_tuple in data_iter:\n yield tokenizer(from_to_tuple[index])\n\n\n# %% id=\"jU3kVlV5okC-\" tags=[]\n\n\ndef build_vocabulary(spacy_de, spacy_en):\n def tokenize_de(text):\n return tokenize(text, spacy_de)\n\n def tokenize_en(text):\n return tokenize(text, spacy_en)\n\n print(\"Building German Vocabulary ...\")\n train, val, test = datasets.Multi30k(language_pair=(\"de\", \"en\"))\n vocab_src = build_vocab_from_iterator(\n yield_tokens(train + val + test, tokenize_de, index=0),\n min_freq=2,\n specials=[\"\", \"\", \"\", \"\"],\n )\n\n print(\"Building English Vocabulary ...\")\n train, val, test = datasets.Multi30k(language_pair=(\"de\", \"en\"))\n vocab_tgt = build_vocab_from_iterator(\n yield_tokens(train + val + test, tokenize_en, index=1),\n min_freq=2,\n specials=[\"\", \"\", \"\", \"\"],\n )\n\n vocab_src.set_default_index(vocab_src[\"\"])\n vocab_tgt.set_default_index(vocab_tgt[\"\"])\n\n return vocab_src, vocab_tgt\n\n\ndef load_vocab(spacy_de, spacy_en):\n if not exists(\"vocab.pt\"):\n vocab_src, vocab_tgt = build_vocabulary(spacy_de, spacy_en)\n torch.save((vocab_src, vocab_tgt), \"vocab.pt\")\n else:\n vocab_src, vocab_tgt = torch.load(\"vocab.pt\")\n print(\"Finished.\\nVocabulary sizes:\")\n print(len(vocab_src))\n print(len(vocab_tgt))\n return vocab_src, vocab_tgt\n\n\nif is_interactive_notebook():\n # global variables used later in the script\n spacy_de, spacy_en = show_example(load_tokenizers)\n vocab_src, vocab_tgt = show_example(load_vocab, args=[spacy_de, spacy_en])\n\n\n# %% [markdown] id=\"-l-TFwzfTsqL\"\n#\n# > Batching matters a ton for speed. We want to have very evenly\n# > divided batches, with absolutely minimal padding. To do this we\n# > have to hack a bit around the default torchtext batching. This\n# > code patches their default batching to make sure we search over\n# > enough sentences to find tight batches.\n\n# %% [markdown] id=\"kDEj-hCgokC-\" tags=[] jp-MarkdownHeadingCollapsed=true\n# ## Iterators\n\n# %% id=\"wGsIHFgOokC_\" tags=[]\ndef collate_batch(\n batch,\n src_pipeline,\n tgt_pipeline,\n src_vocab,\n tgt_vocab,\n device,\n max_padding=128,\n pad_id=2,\n):\n bs_id = torch.tensor([0], device=device) # token id\n eos_id = torch.tensor([1], device=device) # token id\n src_list, tgt_list = [], []\n for (_src, _tgt) in batch:\n processed_src = torch.cat(\n [\n bs_id,\n torch.tensor(\n src_vocab(src_pipeline(_src)),\n dtype=torch.int64,\n device=device,\n ),\n eos_id,\n ],\n 0,\n )\n processed_tgt = torch.cat(\n [\n bs_id,\n torch.tensor(\n tgt_vocab(tgt_pipeline(_tgt)),\n dtype=torch.int64,\n device=device,\n ),\n eos_id,\n ],\n 0,\n )\n src_list.append(\n # warning - overwrites values for negative values of padding - len\n pad(\n processed_src,\n (\n 0,\n max_padding - len(processed_src),\n ),\n value=pad_id,\n )\n )\n tgt_list.append(\n pad(\n processed_tgt,\n (0, max_padding - len(processed_tgt)),\n value=pad_id,\n )\n )\n\n src = torch.stack(src_list)\n tgt = torch.stack(tgt_list)\n return (src, tgt)\n\n\n# %% id=\"ka2Ce_WIokC_\" tags=[]\ndef create_dataloaders(\n device,\n vocab_src,\n vocab_tgt,\n spacy_de,\n spacy_en,\n batch_size=12000,\n max_padding=128,\n is_distributed=True,\n):\n # def create_dataloaders(batch_size=12000):\n def tokenize_de(text):\n return tokenize(text, spacy_de)\n\n def tokenize_en(text):\n return tokenize(text, spacy_en)\n\n def collate_fn(batch):\n return collate_batch(\n batch,\n tokenize_de,\n tokenize_en,\n vocab_src,\n vocab_tgt,\n device,\n max_padding=max_padding,\n pad_id=vocab_src.get_stoi()[\"\"],\n )\n\n train_iter, valid_iter, test_iter = datasets.Multi30k(\n language_pair=(\"de\", \"en\")\n )\n\n train_iter_map = to_map_style_dataset(\n train_iter\n ) # DistributedSampler needs a dataset len()\n train_sampler = (\n DistributedSampler(train_iter_map) if is_distributed else None\n )\n valid_iter_map = to_map_style_dataset(valid_iter)\n valid_sampler = (\n DistributedSampler(valid_iter_map) if is_distributed else None\n )\n\n train_dataloader = DataLoader(\n train_iter_map,\n batch_size=batch_size,\n shuffle=(train_sampler is None),\n sampler=train_sampler,\n collate_fn=collate_fn,\n )\n valid_dataloader = DataLoader(\n valid_iter_map,\n batch_size=batch_size,\n shuffle=(valid_sampler is None),\n sampler=valid_sampler,\n collate_fn=collate_fn,\n )\n return train_dataloader, valid_dataloader\n\n\n# %% [markdown] id=\"90qM8RzCTsqM\"\n# ## Training the System\n\n# %%\ndef train_worker(\n gpu,\n ngpus_per_node,\n vocab_src,\n vocab_tgt,\n spacy_de,\n spacy_en,\n config,\n is_distributed=False,\n):\n print(f\"Train worker process using GPU: {gpu} for training\", flush=True)\n torch.cuda.set_device(gpu)\n\n pad_idx = vocab_tgt[\"\"]\n d_model = 512\n model = make_model(len(vocab_src), len(vocab_tgt), N=6)\n model.cuda(gpu)\n module = model\n is_main_process = True\n if is_distributed:\n dist.init_process_group(\n \"nccl\", init_method=\"env://\", rank=gpu, world_size=ngpus_per_node\n )\n model = DDP(model, device_ids=[gpu])\n module = model.module\n is_main_process = gpu == 0\n\n criterion = LabelSmoothing(\n size=len(vocab_tgt), padding_idx=pad_idx, smoothing=0.1\n )\n criterion.cuda(gpu)\n\n train_dataloader, valid_dataloader = create_dataloaders(\n gpu,\n vocab_src,\n vocab_tgt,\n spacy_de,\n spacy_en,\n batch_size=config[\"batch_size\"] // ngpus_per_node,\n max_padding=config[\"max_padding\"],\n is_distributed=is_distributed,\n )\n\n optimizer = torch.optim.Adam(\n model.parameters(), lr=config[\"base_lr\"], betas=(0.9, 0.98), eps=1e-9\n )\n lr_scheduler = LambdaLR(\n optimizer=optimizer,\n lr_lambda=lambda step: rate(\n step, d_model, factor=1, warmup=config[\"warmup\"]\n ),\n )\n train_state = TrainState()\n\n for epoch in range(config[\"num_epochs\"]):\n if is_distributed:\n train_dataloader.sampler.set_epoch(epoch)\n valid_dataloader.sampler.set_epoch(epoch)\n\n model.train()\n print(f\"[GPU{gpu}] Epoch {epoch} Training ====\", flush=True)\n _, train_state = run_epoch(\n (Batch(b[0], b[1], pad_idx) for b in train_dataloader),\n model,\n SimpleLossCompute(module.generator, criterion),\n optimizer,\n lr_scheduler,\n mode=\"train+log\",\n accum_iter=config[\"accum_iter\"],\n train_state=train_state,\n )\n\n GPUtil.showUtilization()\n if is_main_process:\n file_path = \"%s%.2d.pt\" % (config[\"file_prefix\"], epoch)\n torch.save(module.state_dict(), file_path)\n torch.cuda.empty_cache()\n\n print(f\"[GPU{gpu}] Epoch {epoch} Validation ====\", flush=True)\n model.eval()\n sloss = run_epoch(\n (Batch(b[0], b[1], pad_idx) for b in valid_dataloader),\n model,\n SimpleLossCompute(module.generator, criterion),\n DummyOptimizer(),\n DummyScheduler(),\n mode=\"eval\",\n )\n print(sloss)\n torch.cuda.empty_cache()\n\n if is_main_process:\n file_path = \"%sfinal.pt\" % config[\"file_prefix\"]\n torch.save(module.state_dict(), file_path)\n\n\n# %% tags=[]\ndef train_distributed_model(vocab_src, vocab_tgt, spacy_de, spacy_en, config):\n from the_annotated_transformer import train_worker\n\n ngpus = torch.cuda.device_count()\n os.environ[\"MASTER_ADDR\"] = \"localhost\"\n os.environ[\"MASTER_PORT\"] = \"12356\"\n print(f\"Number of GPUs detected: {ngpus}\")\n print(\"Spawning training processes ...\")\n mp.spawn(\n train_worker,\n nprocs=ngpus,\n args=(ngpus, vocab_src, vocab_tgt, spacy_de, spacy_en, config, True),\n )\n\n\ndef train_model(vocab_src, vocab_tgt, spacy_de, spacy_en, config):\n if config[\"distributed\"]:\n train_distributed_model(\n vocab_src, vocab_tgt, spacy_de, spacy_en, config\n )\n else:\n train_worker(\n 0, 1, vocab_src, vocab_tgt, spacy_de, spacy_en, config, False\n )\n\n\ndef load_trained_model():\n config = {\n \"batch_size\": 32,\n \"distributed\": False,\n \"num_epochs\": 8,\n \"accum_iter\": 10,\n \"base_lr\": 1.0,\n \"max_padding\": 72,\n \"warmup\": 3000,\n \"file_prefix\": \"multi30k_model_\",\n }\n model_path = \"multi30k_model_final.pt\"\n if not exists(model_path):\n train_model(vocab_src, vocab_tgt, spacy_de, spacy_en, config)\n\n model = make_model(len(vocab_src), len(vocab_tgt), N=6)\n model.load_state_dict(torch.load(\"multi30k_model_final.pt\"))\n return model\n\n\nif is_interactive_notebook():\n model = load_trained_model()\n\n\n# %% [markdown] id=\"RZK_VjDPTsqN\"\n#\n# > Once trained we can decode the model to produce a set of\n# > translations. Here we simply translate the first sentence in the\n# > validation set. This dataset is pretty small so the translations\n# > with greedy search are reasonably accurate.\n\n# %% [markdown] id=\"L50i0iEXTsqN\"\n# # Additional Components: BPE, Search, Averaging\n\n# %% [markdown] id=\"NBx1C2_NTsqN\"\n#\n# > So this mostly covers the transformer model itself. There are four\n# > aspects that we didn't cover explicitly. We also have all these\n# > additional features implemented in\n# > [OpenNMT-py](https://github.com/opennmt/opennmt-py).\n#\n#\n\n# %% [markdown] id=\"UpqV1mWnTsqN\"\n#\n# > 1) BPE/ Word-piece: We can use a library to first preprocess the\n# > data into subword units. See Rico Sennrich's\n# > [subword-nmt](https://github.com/rsennrich/subword-nmt)\n# > implementation. These models will transform the training data to\n# > look like this:\n\n# %% [markdown] id=\"hwJ_9J0BTsqN\"\n# ▁Die ▁Protokoll datei ▁kann ▁ heimlich ▁per ▁E - Mail ▁oder ▁FTP\n# ▁an ▁einen ▁bestimmte n ▁Empfänger ▁gesendet ▁werden .\n\n# %% [markdown] id=\"9HwejYkpTsqN\"\n#\n# > 2) Shared Embeddings: When using BPE with shared vocabulary we can\n# > share the same weight vectors between the source / target /\n# > generator. See the [(cite)](https://arxiv.org/abs/1608.05859) for\n# > details. To add this to the model simply do this:\n\n# %% id=\"tb3j3CYLTsqN\" tags=[]\nif False:\n model.src_embed[0].lut.weight = model.tgt_embeddings[0].lut.weight\n model.generator.lut.weight = model.tgt_embed[0].lut.weight\n\n\n# %% [markdown] id=\"xDKJsSwRTsqN\"\n#\n# > 3) Beam Search: This is a bit too complicated to cover here. See the\n# > [OpenNMT-py](https://github.com/OpenNMT/OpenNMT-py/)\n# > for a pytorch implementation.\n# >\n#\n\n# %% [markdown] id=\"wf3vVYGZTsqN\"\n#\n# > 4) Model Averaging: The paper averages the last k checkpoints to\n# > create an ensembling effect. We can do this after the fact if we\n# > have a bunch of models:\n\n# %% id=\"hAFEa78JokDB\"\ndef average(model, models):\n \"Average models into model\"\n for ps in zip(*[m.params() for m in [model] + models]):\n ps[0].copy_(torch.sum(*ps[1:]) / len(ps[1:]))\n\n\n# %% [markdown] id=\"Kz5BYJ9sTsqO\"\n# # Results\n#\n# On the WMT 2014 English-to-German translation task, the big\n# transformer model (Transformer (big) in Table 2) outperforms the\n# best previously reported models (including ensembles) by more than\n# 2.0 BLEU, establishing a new state-of-the-art BLEU score of\n# 28.4. The configuration of this model is listed in the bottom line\n# of Table 3. Training took 3.5 days on 8 P100 GPUs. Even our base\n# model surpasses all previously published models and ensembles, at a\n# fraction of the training cost of any of the competitive models.\n#\n# On the WMT 2014 English-to-French translation task, our big model\n# achieves a BLEU score of 41.0, outperforming all of the previously\n# published single models, at less than 1/4 the training cost of the\n# previous state-of-the-art model. The Transformer (big) model trained\n# for English-to-French used dropout rate Pdrop = 0.1, instead of 0.3.\n#\n\n# %% [markdown]\n# ![](images/results.png)\n\n# %% [markdown] id=\"cPcnsHvQTsqO\"\n#\n#\n# > With the addtional extensions in the last section, the OpenNMT-py\n# > replication gets to 26.9 on EN-DE WMT. Here I have loaded in those\n# > parameters to our reimplemenation.\n\n# %%\n# Load data and model for output checks\n\n\n# %%\ndef check_outputs(\n valid_dataloader,\n model,\n vocab_src,\n vocab_tgt,\n n_examples=15,\n pad_idx=2,\n eos_string=\"\",\n):\n results = [()] * n_examples\n for idx in range(n_examples):\n print(\"\\nExample %d ========\\n\" % idx)\n b = next(iter(valid_dataloader))\n rb = Batch(b[0], b[1], pad_idx)\n greedy_decode(model, rb.src, rb.src_mask, 64, 0)[0]\n\n src_tokens = [\n vocab_src.get_itos()[x] for x in rb.src[0] if x != pad_idx\n ]\n tgt_tokens = [\n vocab_tgt.get_itos()[x] for x in rb.tgt[0] if x != pad_idx\n ]\n\n print(\n \"Source Text (Input) : \"\n + \" \".join(src_tokens).replace(\"\\n\", \"\")\n )\n print(\n \"Target Text (Ground Truth) : \"\n + \" \".join(tgt_tokens).replace(\"\\n\", \"\")\n )\n model_out = greedy_decode(model, rb.src, rb.src_mask, 72, 0)[0]\n model_txt = (\n \" \".join(\n [vocab_tgt.get_itos()[x] for x in model_out if x != pad_idx]\n ).split(eos_string, 1)[0]\n + eos_string\n )\n print(\"Model Output : \" + model_txt.replace(\"\\n\", \"\"))\n results[idx] = (rb, src_tokens, tgt_tokens, model_out, model_txt)\n return results\n\n\ndef run_model_example(n_examples=5):\n global vocab_src, vocab_tgt, spacy_de, spacy_en\n\n print(\"Preparing Data ...\")\n _, valid_dataloader = create_dataloaders(\n torch.device(\"cpu\"),\n vocab_src,\n vocab_tgt,\n spacy_de,\n spacy_en,\n batch_size=1,\n is_distributed=False,\n )\n\n print(\"Loading Trained Model ...\")\n\n model = make_model(len(vocab_src), len(vocab_tgt), N=6)\n model.load_state_dict(\n torch.load(\"multi30k_model_final.pt\", map_location=torch.device(\"cpu\"))\n )\n\n print(\"Checking Model Outputs:\")\n example_data = check_outputs(\n valid_dataloader, model, vocab_src, vocab_tgt, n_examples=n_examples\n )\n return model, example_data\n\n\n# execute_example(run_model_example)\n\n\n# %% [markdown] id=\"0ZkkNTKLTsqO\"\n# ## Attention Visualization\n#\n# > Even with a greedy decoder the translation looks pretty good. We\n# > can further visualize it to see what is happening at each layer of\n# > the attention\n\n# %%\ndef mtx2df(m, max_row, max_col, row_tokens, col_tokens):\n \"convert a dense matrix to a data frame with row and column indices\"\n return pd.DataFrame(\n [\n (\n r,\n c,\n float(m[r, c]),\n \"%.3d %s\"\n % (r, row_tokens[r] if len(row_tokens) > r else \"\"),\n \"%.3d %s\"\n % (c, col_tokens[c] if len(col_tokens) > c else \"\"),\n )\n for r in range(m.shape[0])\n for c in range(m.shape[1])\n if r < max_row and c < max_col\n ],\n # if float(m[r,c]) != 0 and r < max_row and c < max_col],\n columns=[\"row\", \"column\", \"value\", \"row_token\", \"col_token\"],\n )\n\n\ndef attn_map(attn, layer, head, row_tokens, col_tokens, max_dim=30):\n df = mtx2df(\n attn[0, head].data,\n max_dim,\n max_dim,\n row_tokens,\n col_tokens,\n )\n return (\n alt.Chart(data=df)\n .mark_rect()\n .encode(\n x=alt.X(\"col_token\", axis=alt.Axis(title=\"\")),\n y=alt.Y(\"row_token\", axis=alt.Axis(title=\"\")),\n color=\"value\",\n tooltip=[\"row\", \"column\", \"value\", \"row_token\", \"col_token\"],\n )\n .properties(height=400, width=400)\n .interactive()\n )\n\n\n# %% tags=[]\ndef get_encoder(model, layer):\n return model.encoder.layers[layer].self_attn.attn\n\n\ndef get_decoder_self(model, layer):\n return model.decoder.layers[layer].self_attn.attn\n\n\ndef get_decoder_src(model, layer):\n return model.decoder.layers[layer].src_attn.attn\n\n\ndef visualize_layer(model, layer, getter_fn, ntokens, row_tokens, col_tokens):\n # ntokens = last_example[0].ntokens\n attn = getter_fn(model, layer)\n n_heads = attn.shape[1]\n charts = [\n attn_map(\n attn,\n 0,\n h,\n row_tokens=row_tokens,\n col_tokens=col_tokens,\n max_dim=ntokens,\n )\n for h in range(n_heads)\n ]\n assert n_heads == 8\n return alt.vconcat(\n charts[0]\n # | charts[1]\n | charts[2]\n # | charts[3]\n | charts[4]\n # | charts[5]\n | charts[6]\n # | charts[7]\n # layer + 1 due to 0-indexing\n ).properties(title=\"Layer %d\" % (layer + 1))\n\n\n# %% [markdown]\n# ## Encoder Self Attention\n\n# %% tags=[]\ndef viz_encoder_self():\n model, example_data = run_model_example(n_examples=1)\n example = example_data[\n len(example_data) - 1\n ] # batch object for the final example\n\n layer_viz = [\n visualize_layer(\n model, layer, get_encoder, len(example[1]), example[1], example[1]\n )\n for layer in range(6)\n ]\n return alt.hconcat(\n layer_viz[0]\n # & layer_viz[1]\n & layer_viz[2]\n # & layer_viz[3]\n & layer_viz[4]\n # & layer_viz[5]\n )\n\n\nshow_example(viz_encoder_self)\n\n\n# %% [markdown]\n# ## Decoder Self Attention\n\n# %% tags=[]\ndef viz_decoder_self():\n model, example_data = run_model_example(n_examples=1)\n example = example_data[len(example_data) - 1]\n\n layer_viz = [\n visualize_layer(\n model,\n layer,\n get_decoder_self,\n len(example[1]),\n example[1],\n example[1],\n )\n for layer in range(6)\n ]\n return alt.hconcat(\n layer_viz[0]\n & layer_viz[1]\n & layer_viz[2]\n & layer_viz[3]\n & layer_viz[4]\n & layer_viz[5]\n )\n\n\nshow_example(viz_decoder_self)\n\n\n# %% [markdown]\n# ## Decoder Src Attention\n\n# %% tags=[]\ndef viz_decoder_src():\n model, example_data = run_model_example(n_examples=1)\n example = example_data[len(example_data) - 1]\n\n layer_viz = [\n visualize_layer(\n model,\n layer,\n get_decoder_src,\n max(len(example[1]), len(example[2])),\n example[1],\n example[2],\n )\n for layer in range(6)\n ]\n return alt.hconcat(\n layer_viz[0]\n & layer_viz[1]\n & layer_viz[2]\n & layer_viz[3]\n & layer_viz[4]\n & layer_viz[5]\n )\n\n\nshow_example(viz_decoder_src)\n\n# %% [markdown] id=\"nSseuCcATsqO\"\n# # Conclusion\n#\n# Hopefully this code is useful for future research. Please reach\n# out if you have any issues.\n#\n#\n# Cheers,\n# Sasha Rush, Austin Huang, Suraj Subramanian, Jonathan Sum, Khalid Almubarak,\n# Stella Biderman\n" }, { "path": "writeup/acl2018.sty", "content": "\n%\n% 2018: modified line numbering to be in gainsboro gray color so one\n% can write comments on the margins.\t-- Shay Cohen / Kevin Gimpel / Wei Lu\n\n% 2017: modified to support DOI links in bibliography. Now uses\n% natbib package rather than defining citation commands in this file.\n% Use with acl_natbib.bst bib style. -- Dan Gildea\n\n% This is the LaTeX style for ACL 2016. It contains Margaret Mitchell's\n% line number adaptations (ported by Hai Zhao and Yannick Versley).\n\n% It is nearly identical to the style files for ACL 2015,\n% ACL 2014, EACL 2006, ACL2005, ACL 2002, ACL 2001, ACL 2000,\n% EACL 95 and EACL 99. \n%\n% Changes made include: adapt layout to A4 and centimeters, widen abstract\n\n% This is the LaTeX style file for ACL 2000. It is nearly identical to the\n% style files for EACL 95 and EACL 99. Minor changes include editing the\n% instructions to reflect use of \\documentclass rather than \\documentstyle\n% and removing the white space before the title on the first page\n% -- John Chen, June 29, 2000\n\n% This is the LaTeX style file for EACL-95. It is identical to the\n% style file for ANLP '94 except that the margins are adjusted for A4\n% paper. -- abney 13 Dec 94\n\n% The ANLP '94 style file is a slightly modified\n% version of the style used for AAAI and IJCAI, using some changes\n% prepared by Fernando Pereira and others and some minor changes \n% by Paul Jacobs.\n\n% Papers prepared using the aclsub.sty file and acl.bst bibtex style\n% should be easily converted to final format using this style. \n% (1) Submission information (\\wordcount, \\subject, and \\makeidpage)\n% should be removed.\n% (2) \\summary should be removed. The summary material should come\n% after \\maketitle and should be in the ``abstract'' environment\n% (between \\begin{abstract} and \\end{abstract}).\n% (3) Check all citations. This style should handle citations correctly\n% and also allows multiple citations separated by semicolons.\n% (4) Check figures and examples. Because the final format is double-\n% column, some adjustments may have to be made to fit text in the column\n% or to choose full-width (\\figure*} figures.\n\n% Place this in a file called aclap.sty in the TeX search path. \n% (Placing it in the same directory as the paper should also work.)\n\n% Prepared by Peter F. Patel-Schneider, liberally using the ideas of\n% other style hackers, including Barbara Beeton.\n% This style is NOT guaranteed to work. It is provided in the hope\n% that it will make the preparation of papers easier.\n%\n% There are undoubtably bugs in this style. If you make bug fixes,\n% improvements, etc. please let me know. My e-mail address is:\n% pfps@research.att.com\n\n% Papers are to be prepared using the ``acl_natbib'' bibliography style,\n% as follows:\n% \\documentclass[11pt]{article}\n% \\usepackage{acl2000}\n% \\title{Title}\n% \\author{Author 1 \\and Author 2 \\\\ Address line \\\\ Address line \\And\n% Author 3 \\\\ Address line \\\\ Address line}\n% \\begin{document}\n% ...\n% \\bibliography{bibliography-file}\n% \\bibliographystyle{acl_natbib}\n% \\end{document}\n\n% Author information can be set in various styles:\n% For several authors from the same institution:\n% \\author{Author 1 \\and ... \\and Author n \\\\\n% Address line \\\\ ... \\\\ Address line}\n% if the names do not fit well on one line use\n% Author 1 \\\\ {\\bf Author 2} \\\\ ... \\\\ {\\bf Author n} \\\\\n% For authors from different institutions:\n% \\author{Author 1 \\\\ Address line \\\\ ... \\\\ Address line\n% \\And ... \\And\n% Author n \\\\ Address line \\\\ ... \\\\ Address line}\n% To start a seperate ``row'' of authors use \\AND, as in\n% \\author{Author 1 \\\\ Address line \\\\ ... \\\\ Address line\n% \\AND\n% Author 2 \\\\ Address line \\\\ ... \\\\ Address line \\And\n% Author 3 \\\\ Address line \\\\ ... \\\\ Address line}\n\n% If the title and author information does not fit in the area allocated,\n% place \\setlength\\titlebox{} right after\n% \\usepackage{acl2015}\n% where can be something larger than 5cm\n\n% include hyperref, unless user specifies nohyperref option like this:\n% \\usepackage[nohyperref]{acl2018}\n\\newif\\ifacl@hyperref\n\\DeclareOption{hyperref}{\\acl@hyperreftrue}\n\\DeclareOption{nohyperref}{\\acl@hyperreffalse}\n\\ExecuteOptions{hyperref} % default is to use hyperref\n\\ProcessOptions\\relax\n\\ifacl@hyperref\n \\RequirePackage{hyperref}\n \\usepackage{xcolor}\t\t% make links dark blue\n \\definecolor{darkblue}{rgb}{0, 0, 0.5}\n \\hypersetup{colorlinks=true,citecolor=darkblue, linkcolor=darkblue, urlcolor=darkblue}\n\\else\n % This definition is used if the hyperref package is not loaded.\n % It provides a backup, no-op definiton of \\href.\n % This is necessary because \\href command is used in the acl_natbib.bst file.\n \\def\\href#1#2{{#2}}\n % We still need to load xcolor in this case because the lighter line numbers require it. (SC/KG/WL) \n \\usepackage{xcolor}\n\\fi\n\n\\typeout{Conference Style for ACL 2018}\n\n% NOTE: Some laser printers have a serious problem printing TeX output.\n% These printing devices, commonly known as ``write-white'' laser\n% printers, tend to make characters too light. To get around this\n% problem, a darker set of fonts must be created for these devices.\n%\n\n\\newcommand{\\Thanks}[1]{\\thanks{\\ #1}}\n\n% A4 modified by Eneko; again modified by Alexander for 5cm titlebox\n\\setlength{\\paperwidth}{21cm} % A4\n\\setlength{\\paperheight}{29.7cm}% A4\n\\setlength\\topmargin{-0.5cm} \n\\setlength\\oddsidemargin{0cm} \n\\setlength\\textheight{24.7cm} \n\\setlength\\textwidth{16.0cm}\n\\setlength\\columnsep{0.6cm} \n\\newlength\\titlebox \n\\setlength\\titlebox{5cm}\n\\setlength\\headheight{5pt} \n\\setlength\\headsep{0pt}\n\\thispagestyle{empty} \n\\pagestyle{empty}\n\n\n\\flushbottom \\twocolumn \\sloppy\n\n% We're never going to need a table of contents, so just flush it to\n% save space --- suggested by drstrip@sandia-2\n\\def\\addcontentsline#1#2#3{}\n\n\\newif\\ifaclfinal\n\\aclfinalfalse\n\\def\\aclfinalcopy{\\global\\aclfinaltrue}\n\n%% ----- Set up hooks to repeat content on every page of the output doc, \n%% necessary for the line numbers in the submitted version. --MM\n%%\n%% Copied from CVPR 2015's cvpr_eso.sty, which appears to be largely copied from everyshi.sty.\n%%\n%% Original cvpr_eso.sty available at: http://www.pamitc.org/cvpr15/author_guidelines.php\n%% Original evershi.sty available at: https://www.ctan.org/pkg/everyshi\n%%\n%% Copyright (C) 2001 Martin Schr\\\"oder:\n%% \n%% Martin Schr\"oder\n%% Cr\"usemannallee 3\n%% D-28213 Bremen\n%% Martin.Schroeder@ACM.org\n%% \n%% This program may be redistributed and/or modified under the terms\n%% of the LaTeX Project Public License, either version 1.0 of this\n%% license, or (at your option) any later version.\n%% The latest version of this license is in\n%% CTAN:macros/latex/base/lppl.txt.\n%% \n%% Happy users are requested to send [Martin] a postcard. :-)\n%%\n\\newcommand{\\@EveryShipoutACL@Hook}{}\n\\newcommand{\\@EveryShipoutACL@AtNextHook}{}\n\\newcommand*{\\EveryShipoutACL}[1]\n {\\g@addto@macro\\@EveryShipoutACL@Hook{#1}}\n\\newcommand*{\\AtNextShipoutACL@}[1]\n {\\g@addto@macro\\@EveryShipoutACL@AtNextHook{#1}}\n\\newcommand{\\@EveryShipoutACL@Shipout}{%\n \\afterassignment\\@EveryShipoutACL@Test\n \\global\\setbox\\@cclv= %\n }\n\\newcommand{\\@EveryShipoutACL@Test}{%\n \\ifvoid\\@cclv\\relax\n \\aftergroup\\@EveryShipoutACL@Output\n \\else\n \\@EveryShipoutACL@Output\n \\fi%\n }\n\\newcommand{\\@EveryShipoutACL@Output}{%\n \\@EveryShipoutACL@Hook%\n \\@EveryShipoutACL@AtNextHook%\n \\gdef\\@EveryShipoutACL@AtNextHook{}%\n \\@EveryShipoutACL@Org@Shipout\\box\\@cclv%\n }\n\\newcommand{\\@EveryShipoutACL@Org@Shipout}{}\n\\newcommand*{\\@EveryShipoutACL@Init}{%\n \\message{ABD: EveryShipout initializing macros}%\n \\let\\@EveryShipoutACL@Org@Shipout\\shipout\n \\let\\shipout\\@EveryShipoutACL@Shipout\n }\n\\AtBeginDocument{\\@EveryShipoutACL@Init}\n\n%% ----- Set up for placing additional items into the submitted version --MM\n%%\n%% Based on eso-pic.sty\n%%\n%% Original available at: https://www.ctan.org/tex-archive/macros/latex/contrib/eso-pic\n%% Copyright (C) 1998-2002 by Rolf Niepraschk \n%% \n%% Which may be distributed and/or modified under the conditions of\n%% the LaTeX Project Public License, either version 1.2 of this license\n%% or (at your option) any later version. The latest version of this\n%% license is in:\n%% \n%% http://www.latex-project.org/lppl.txt\n%% \n%% and version 1.2 or later is part of all distributions of LaTeX version\n%% 1999/12/01 or later.\n%%\n%% In contrast to the original, we do not include the definitions for/using:\n%% gridpicture, div[2], isMEMOIR[1], gridSetup[6][], subgridstyle{dotted}, labelfactor{}, gap{}, gridunitname{}, gridunit{}, gridlines{\\thinlines}, subgridlines{\\thinlines}, the {keyval} package, evenside margin, nor any definitions with 'color'.\n%%\n%% These are beyond what is needed for the NAACL style.\n%%\n\\newcommand\\LenToUnit[1]{#1\\@gobble}\n\\newcommand\\AtPageUpperLeft[1]{%\n \\begingroup\n \\@tempdima=0pt\\relax\\@tempdimb=\\ESO@yoffsetI\\relax\n \\put(\\LenToUnit{\\@tempdima},\\LenToUnit{\\@tempdimb}){#1}%\n \\endgroup\n}\n\\newcommand\\AtPageLowerLeft[1]{\\AtPageUpperLeft{%\n \\put(0,\\LenToUnit{-\\paperheight}){#1}}}\n\\newcommand\\AtPageCenter[1]{\\AtPageUpperLeft{%\n \\put(\\LenToUnit{.5\\paperwidth},\\LenToUnit{-.5\\paperheight}){#1}}}\n\\newcommand\\AtPageLowerCenter[1]{\\AtPageUpperLeft{%\n \\put(\\LenToUnit{.5\\paperwidth},\\LenToUnit{-\\paperheight}){#1}}}%\n\\newcommand\\AtPageLowishCenter[1]{\\AtPageUpperLeft{%\n \\put(\\LenToUnit{.5\\paperwidth},\\LenToUnit{-.96\\paperheight}){#1}}}\n\\newcommand\\AtTextUpperLeft[1]{%\n \\begingroup\n \\setlength\\@tempdima{1in}%\n \\advance\\@tempdima\\oddsidemargin%\n \\@tempdimb=\\ESO@yoffsetI\\relax\\advance\\@tempdimb-1in\\relax%\n \\advance\\@tempdimb-\\topmargin%\n \\advance\\@tempdimb-\\headheight\\advance\\@tempdimb-\\headsep%\n \\put(\\LenToUnit{\\@tempdima},\\LenToUnit{\\@tempdimb}){#1}%\n \\endgroup\n}\n\\newcommand\\AtTextLowerLeft[1]{\\AtTextUpperLeft{%\n \\put(0,\\LenToUnit{-\\textheight}){#1}}}\n\\newcommand\\AtTextCenter[1]{\\AtTextUpperLeft{%\n \\put(\\LenToUnit{.5\\textwidth},\\LenToUnit{-.5\\textheight}){#1}}}\n\\newcommand{\\ESO@HookI}{} \\newcommand{\\ESO@HookII}{}\n\\newcommand{\\ESO@HookIII}{}\n\\newcommand{\\AddToShipoutPicture}{%\n \\@ifstar{\\g@addto@macro\\ESO@HookII}{\\g@addto@macro\\ESO@HookI}}\n\\newcommand{\\ClearShipoutPicture}{\\global\\let\\ESO@HookI\\@empty}\n\\newcommand{\\@ShipoutPicture}{%\n \\bgroup\n \\@tempswafalse%\n \\ifx\\ESO@HookI\\@empty\\else\\@tempswatrue\\fi%\n \\ifx\\ESO@HookII\\@empty\\else\\@tempswatrue\\fi%\n \\ifx\\ESO@HookIII\\@empty\\else\\@tempswatrue\\fi%\n \\if@tempswa%\n \\@tempdima=1in\\@tempdimb=-\\@tempdima%\n \\advance\\@tempdimb\\ESO@yoffsetI%\n \\unitlength=1pt%\n \\global\\setbox\\@cclv\\vbox{%\n \\vbox{\\let\\protect\\relax\n \\pictur@(0,0)(\\strip@pt\\@tempdima,\\strip@pt\\@tempdimb)%\n \\ESO@HookIII\\ESO@HookI\\ESO@HookII%\n \\global\\let\\ESO@HookII\\@empty%\n \\endpicture}%\n \\nointerlineskip%\n \\box\\@cclv}%\n \\fi\n \\egroup\n}\n\\EveryShipoutACL{\\@ShipoutPicture}\n\\newif\\ifESO@dvips\\ESO@dvipsfalse \n\\newif\\ifESO@grid\\ESO@gridfalse\n\\newif\\ifESO@texcoord\\ESO@texcoordfalse\n\\newcommand*\\ESO@griddelta{}\\newcommand*\\ESO@griddeltaY{}\n\\newcommand*\\ESO@gridDelta{}\\newcommand*\\ESO@gridDeltaY{}\n\\newcommand*\\ESO@yoffsetI{}\\newcommand*\\ESO@yoffsetII{}\n\\ifESO@texcoord\n \\def\\ESO@yoffsetI{0pt}\\def\\ESO@yoffsetII{-\\paperheight}\n \\edef\\ESO@griddeltaY{-\\ESO@griddelta}\\edef\\ESO@gridDeltaY{-\\ESO@gridDelta}\n\\else\n \\def\\ESO@yoffsetI{\\paperheight}\\def\\ESO@yoffsetII{0pt}\n \\edef\\ESO@griddeltaY{\\ESO@griddelta}\\edef\\ESO@gridDeltaY{\\ESO@gridDelta}\n\\fi\n\n\n%% ----- Submitted version markup: Page numbers, ruler, and confidentiality. Using ideas/code from cvpr.sty 2015. --MM\n\n\\font\\naaclhv = phvb at 8pt \n\n%% Define vruler %%\n\n%\\makeatletter\n\\newbox\\aclrulerbox\n\\newcount\\aclrulercount\n\\newdimen\\aclruleroffset\n\\newdimen\\cv@lineheight\n\\newdimen\\cv@boxheight\n\\newbox\\cv@tmpbox\n\\newcount\\cv@refno\n\\newcount\\cv@tot\n% NUMBER with left flushed zeros \\fillzeros[]\n\\newcount\\cv@tmpc@ \\newcount\\cv@tmpc\n\\def\\fillzeros[#1]#2{\\cv@tmpc@=#2\\relax\\ifnum\\cv@tmpc@<0\\cv@tmpc@=-\\cv@tmpc@\\fi\n\\cv@tmpc=1 %\n\\loop\\ifnum\\cv@tmpc@<10 \\else \\divide\\cv@tmpc@ by 10 \\advance\\cv@tmpc by 1 \\fi\n \\ifnum\\cv@tmpc@=10\\relax\\cv@tmpc@=11\\relax\\fi \\ifnum\\cv@tmpc@>10 \\repeat\n\\ifnum#2<0\\advance\\cv@tmpc1\\relax-\\fi\n\\loop\\ifnum\\cv@tmpc<#1\\relax0\\advance\\cv@tmpc1\\relax\\fi \\ifnum\\cv@tmpc<#1 \\repeat\n\\cv@tmpc@=#2\\relax\\ifnum\\cv@tmpc@<0\\cv@tmpc@=-\\cv@tmpc@\\fi \\relax\\the\\cv@tmpc@}%\n% \\makevruler[][][][][]\n\\def\\makevruler[#1][#2][#3][#4][#5]{\\begingroup\\offinterlineskip\n\\textheight=#5\\vbadness=10000\\vfuzz=120ex\\overfullrule=0pt%\n\\global\\setbox\\aclrulerbox=\\vbox to \\textheight{%\n{\\parskip=0pt\\hfuzz=150em\\cv@boxheight=\\textheight\n\\cv@lineheight=#1\\global\\aclrulercount=#2%\n\\cv@tot\\cv@boxheight\\divide\\cv@tot\\cv@lineheight\\advance\\cv@tot2%\n\\cv@refno1\\vskip-\\cv@lineheight\\vskip1ex%\n\\loop\\setbox\\cv@tmpbox=\\hbox to0cm{{\\naaclhv\\hfil\\fillzeros[#4]\\aclrulercount}}%\n\\ht\\cv@tmpbox\\cv@lineheight\\dp\\cv@tmpbox0pt\\box\\cv@tmpbox\\break\n\\advance\\cv@refno1\\global\\advance\\aclrulercount#3\\relax\n\\ifnum\\cv@refno<\\cv@tot\\repeat}}\\endgroup}%\n%\\makeatother\n\n\n\\def\\aclpaperid{***}\n\\def\\confidential{ACL 2018 Submission~\\aclpaperid. Confidential Review Copy. DO NOT DISTRIBUTE.}\n\n%% Page numbering, Vruler and Confidentiality %%\n% \\makevruler[][][][][]\n\n% SC/KG/WL - changed line numbering to gainsboro\n\\definecolor{gainsboro}{rgb}{0.8, 0.8, 0.8}\n%\\def\\aclruler#1{\\makevruler[14.17pt][#1][1][3][\\textheight]\\usebox{\\aclrulerbox}} %% old line\n\\def\\aclruler#1{\\textcolor{gainsboro}{\\makevruler[14.17pt][#1][1][3][\\textheight]\\usebox{\\aclrulerbox}}}\n\n\\def\\leftoffset{-2.1cm} %original: -45pt\n\\def\\rightoffset{17.5cm} %original: 500pt\n\\ifaclfinal\\else\\pagenumbering{arabic}\n\\AddToShipoutPicture{%\n\\ifaclfinal\\else\n\\AtPageLowishCenter{\\thepage}\n\\aclruleroffset=\\textheight\n\\advance\\aclruleroffset4pt\n \\AtTextUpperLeft{%\n \\put(\\LenToUnit{\\leftoffset},\\LenToUnit{-\\aclruleroffset}){%left ruler\n \\aclruler{\\aclrulercount}}\n \\put(\\LenToUnit{\\rightoffset},\\LenToUnit{-\\aclruleroffset}){%right ruler\n \\aclruler{\\aclrulercount}}\n }\n \\AtTextUpperLeft{%confidential\n \\put(0,\\LenToUnit{1cm}){\\parbox{\\textwidth}{\\centering\\naaclhv\\confidential}}\n }\n\\fi\n}\n\n%%%% ----- End settings for placing additional items into the submitted version --MM ----- %%%%\n\n%%%% ----- Begin settings for both submitted and camera-ready version ----- %%%%\n\n%% Title and Authors %%\n\n\\newcommand\\outauthor{\n \\begin{tabular}[t]{c}\n\t\\ifaclfinal \n\t \\bf\\@author\n\t\\else \n\t\t% Avoiding common accidental de-anonymization issue. --MM\n \t\t\\bf Anonymous ACL submission\n\t\\fi\n \\end{tabular}}\n\n% Changing the expanded titlebox for submissions to 2.5 in (rather than 6.5cm)\n% and moving it to the style sheet, rather than within the example tex file. --MM\n\\ifaclfinal \n\\else \n\t\\addtolength\\titlebox{.25in}\n\\fi\n% Mostly taken from deproc.\n\\def\\maketitle{\\par\n \\begingroup\n \\def\\thefootnote{\\fnsymbol{footnote}}\n \\def\\@makefnmark{\\hbox to 0pt{$^{\\@thefnmark}$\\hss}}\n \\twocolumn[\\@maketitle] \\@thanks\n \\endgroup\n \\setcounter{footnote}{0}\n \\let\\maketitle\\relax \\let\\@maketitle\\relax\n \\gdef\\@thanks{}\\gdef\\@author{}\\gdef\\@title{}\\let\\thanks\\relax}\n\\def\\@maketitle{\\vbox to \\titlebox{\\hsize\\textwidth\n \\linewidth\\hsize \\vskip 0.125in minus 0.125in \\centering\n {\\Large\\bf \\@title \\par} \\vskip 0.2in plus 1fil minus 0.1in\n {\\def\\and{\\unskip\\enspace{\\rm and}\\enspace}%\n \\def\\And{\\end{tabular}\\hss \\egroup \\hskip 1in plus 2fil \n \\hbox to 0pt\\bgroup\\hss \\begin{tabular}[t]{c}\\bf}%\n \\def\\AND{\\end{tabular}\\hss\\egroup \\hfil\\hfil\\egroup\n \\vskip 0.25in plus 1fil minus 0.125in\n \\hbox to \\linewidth\\bgroup\\large \\hfil\\hfil\n \\hbox to 0pt\\bgroup\\hss \\begin{tabular}[t]{c}\\bf}\n \\hbox to \\linewidth\\bgroup\\large \\hfil\\hfil\n \\hbox to 0pt\\bgroup\\hss \n\t\\outauthor\n \\hss\\egroup\n \\hfil\\hfil\\egroup}\n \\vskip 0.3in plus 2fil minus 0.1in\n}}\n\n% margins for abstract\n\\renewenvironment{abstract}%\n\t\t {\\centerline{\\large\\bf Abstract}%\n\t\t \\begin{list}{}%\n\t\t {\\setlength{\\rightmargin}{0.6cm}%\n\t\t \\setlength{\\leftmargin}{0.6cm}}%\n\t\t \\item[]\\ignorespaces}%\n\t\t {\\unskip\\end{list}}\n\t\t \n%\\renewenvironment{abstract}{\\centerline{\\large\\bf \n% Abstract}\\vspace{0.5ex}\\begin{quote}}{\\par\\end{quote}\\vskip 1ex}\n\n\\RequirePackage{natbib}\n% for citation commands in the .tex, authors can use:\n% \\citep, \\citet, and \\citeyearpar for compatibility with natbib, or\n% \\cite, \\newcite, and \\shortcite for compatibility with older ACL .sty files\n\\renewcommand\\cite{\\citep}\t% to get \"(Author Year)\" with natbib \n\\newcommand\\shortcite{\\citeyearpar}% to get \"(Year)\" with natbib \n\\newcommand\\newcite{\\citet}\t% to get \"Author (Year)\" with natbib \n\n% bibliography\n\n\\def\\@up#1{\\raise.2ex\\hbox{#1}}\n\n% Don't put a label in the bibliography at all. Just use the unlabeled format\n% instead.\n\\def\\thebibliography#1{\\vskip\\parskip%\n\\vskip\\baselineskip%\n\\def\\baselinestretch{1}%\n\\ifx\\@currsize\\normalsize\\@normalsize\\else\\@currsize\\fi%\n\\vskip-\\parskip%\n\\vskip-\\baselineskip%\n\\section*{References\\@mkboth\n {References}{References}}\\list\n {}{\\setlength{\\labelwidth}{0pt}\\setlength{\\leftmargin}{\\parindent}\n \\setlength{\\itemindent}{-\\parindent}}\n \\def\\newblock{\\hskip .11em plus .33em minus -.07em}\n \\sloppy\\clubpenalty4000\\widowpenalty4000\n \\sfcode`\\.=1000\\relax}\n\\let\\endthebibliography=\\endlist\n\n\n% Allow for a bibliography of sources of attested examples\n\\def\\thesourcebibliography#1{\\vskip\\parskip%\n\\vskip\\baselineskip%\n\\def\\baselinestretch{1}%\n\\ifx\\@currsize\\normalsize\\@normalsize\\else\\@currsize\\fi%\n\\vskip-\\parskip%\n\\vskip-\\baselineskip%\n\\section*{Sources of Attested Examples\\@mkboth\n {Sources of Attested Examples}{Sources of Attested Examples}}\\list\n {}{\\setlength{\\labelwidth}{0pt}\\setlength{\\leftmargin}{\\parindent}\n \\setlength{\\itemindent}{-\\parindent}}\n \\def\\newblock{\\hskip .11em plus .33em minus -.07em}\n \\sloppy\\clubpenalty4000\\widowpenalty4000\n \\sfcode`\\.=1000\\relax}\n\\let\\endthesourcebibliography=\\endlist\n\n% sections with less space\n\\def\\section{\\@startsection {section}{1}{\\z@}{-2.0ex plus\n -0.5ex minus -.2ex}{1.5ex plus 0.3ex minus .2ex}{\\large\\bf\\raggedright}}\n\\def\\subsection{\\@startsection{subsection}{2}{\\z@}{-1.8ex plus\n -0.5ex minus -.2ex}{0.8ex plus .2ex}{\\normalsize\\bf\\raggedright}}\n%% changed by KO to - values to get teh initial parindent right\n\\def\\subsubsection{\\@startsection{subsubsection}{3}{\\z@}{-1.5ex plus\n -0.5ex minus -.2ex}{0.5ex plus .2ex}{\\normalsize\\bf\\raggedright}}\n\\def\\paragraph{\\@startsection{paragraph}{4}{\\z@}{1.5ex plus\n 0.5ex minus .2ex}{-1em}{\\normalsize\\bf}}\n\\def\\subparagraph{\\@startsection{subparagraph}{5}{\\parindent}{1.5ex plus\n 0.5ex minus .2ex}{-1em}{\\normalsize\\bf}}\n\n% Footnotes\n\\footnotesep 6.65pt %\n\\skip\\footins 9pt plus 4pt minus 2pt\n\\def\\footnoterule{\\kern-3pt \\hrule width 5pc \\kern 2.6pt }\n\\setcounter{footnote}{0}\n\n% Lists and paragraphs\n\\parindent 1em\n\\topsep 4pt plus 1pt minus 2pt\n\\partopsep 1pt plus 0.5pt minus 0.5pt\n\\itemsep 2pt plus 1pt minus 0.5pt\n\\parsep 2pt plus 1pt minus 0.5pt\n\n\\leftmargin 2em \\leftmargini\\leftmargin \\leftmarginii 2em\n\\leftmarginiii 1.5em \\leftmarginiv 1.0em \\leftmarginv .5em \\leftmarginvi .5em\n\\labelwidth\\leftmargini\\advance\\labelwidth-\\labelsep \\labelsep 5pt\n\n\\def\\@listi{\\leftmargin\\leftmargini}\n\\def\\@listii{\\leftmargin\\leftmarginii\n \\labelwidth\\leftmarginii\\advance\\labelwidth-\\labelsep\n \\topsep 2pt plus 1pt minus 0.5pt\n \\parsep 1pt plus 0.5pt minus 0.5pt\n \\itemsep \\parsep}\n\\def\\@listiii{\\leftmargin\\leftmarginiii\n \\labelwidth\\leftmarginiii\\advance\\labelwidth-\\labelsep\n \\topsep 1pt plus 0.5pt minus 0.5pt \n \\parsep \\z@ \\partopsep 0.5pt plus 0pt minus 0.5pt\n \\itemsep \\topsep}\n\\def\\@listiv{\\leftmargin\\leftmarginiv\n \\labelwidth\\leftmarginiv\\advance\\labelwidth-\\labelsep}\n\\def\\@listv{\\leftmargin\\leftmarginv\n \\labelwidth\\leftmarginv\\advance\\labelwidth-\\labelsep}\n\\def\\@listvi{\\leftmargin\\leftmarginvi\n \\labelwidth\\leftmarginvi\\advance\\labelwidth-\\labelsep}\n\n\\abovedisplayskip 7pt plus2pt minus5pt%\n\\belowdisplayskip \\abovedisplayskip\n\\abovedisplayshortskip 0pt plus3pt% \n\\belowdisplayshortskip 4pt plus3pt minus3pt%\n\n% Less leading in most fonts (due to the narrow columns)\n% The choices were between 1-pt and 1.5-pt leading\n\\def\\@normalsize{\\@setsize\\normalsize{11pt}\\xpt\\@xpt}\n\\def\\small{\\@setsize\\small{10pt}\\ixpt\\@ixpt}\n\\def\\footnotesize{\\@setsize\\footnotesize{10pt}\\ixpt\\@ixpt}\n\\def\\scriptsize{\\@setsize\\scriptsize{8pt}\\viipt\\@viipt}\n\\def\\tiny{\\@setsize\\tiny{7pt}\\vipt\\@vipt}\n\\def\\large{\\@setsize\\large{14pt}\\xiipt\\@xiipt}\n\\def\\Large{\\@setsize\\Large{16pt}\\xivpt\\@xivpt}\n\\def\\LARGE{\\@setsize\\LARGE{20pt}\\xviipt\\@xviipt}\n\\def\\huge{\\@setsize\\huge{23pt}\\xxpt\\@xxpt}\n\\def\\Huge{\\@setsize\\Huge{28pt}\\xxvpt\\@xxvpt}\n" }, { "path": "writeup/acl_natbib.bst", "content": "%%% Modification of BibTeX style file acl_natbib_nourl.bst\n%%% ... by urlbst, version 0.7 (marked with \"% urlbst\")\n%%% See \n%%% Added webpage entry type, and url and lastchecked fields.\n%%% Added eprint support.\n%%% Added DOI support.\n%%% Added PUBMED support.\n%%% Added hyperref support.\n%%% Original headers follow...\n\n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n% - fixed a bug with format.chapter - error given in chapter is empty\n% with inbook.\n% Shay Cohen 2018/02/16\n\n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n%\n% BibTeX style file acl_natbib.bst\n%\n% intended as input to urlbst script\n%\n% adapted from compling.bst \n% in order to mimic the style files for ACL conferences prior to 2017\n% by making the following three changes:\n% - for @incollection, page numbers now follow volume title.\n% - for @inproceedings, address now follows conference name.\n%\t(address is intended as location of conference,\n%\t not address of publisher.)\n% - for papers with three authors, use et al. in citation\n% Dan Gildea 2017/06/08\n\n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n%\n% BibTeX style file compling.bst\n%\n% Intended for the journal Computational Linguistics (ACL/MIT Press)\n% Created by Ron Artstein on 2005/08/22 \n% For use with for author-year citations.\n%\n% I created this file in order to allow submissions to the journal \n% Computational Linguistics using the package for author-year\n% citations, which offers a lot more flexibility than , CL's \n% official citation package. This file adheres strictly to the official\n% style guide available from the MIT Press:\n%\n% http://mitpress.mit.edu/journals/coli/compling_style.pdf\n%\n% This includes all the various quirks of the style guide, for example: \n% - a chapter from a monograph (@inbook) has no page numbers.\n% - an article from an edited volume (@incollection) has page numbers\n% after the publisher and address.\n% - an article from a proceedings volume (@inproceedings) has page \n% numbers before the publisher and address.\n%\n% Where the style guide was inconsistent or not specific enough I \n% looked at actual published articles and exercised my own judgment. \n% I noticed two inconsistencies in the style guide:\n%\n% - The style guide gives one example of an article from an edited \n% volume with the editor's name spelled out in full, and another \n% with the editors' names abbreviated. I chose to accept the first \n% one as correct, since the style guide generally shuns abbreviations, \n% and editors' names are also spelled out in some recently published \n% articles.\n%\n% - The style guide gives one example of a reference where the word \n% \"and\" between two authors is preceded by a comma. This is most \n% likely a typo, since in all other cases with just two authors or \n% editors there is no comma before the word \"and\".\n%\n% One case where the style guide is not being specific is the placement\n% of the edition number, for which no example is given. I chose to put \n% it immediately after the title, which I (subjectively) find natural,\n% and is also the place of the edition in a few recently published\n% articles.\n%\n% This file correctly reproduces all of the examples in the official\n% style guide, except for the two inconsistencies noted above. I even\n% managed to get it to correctly format the proceedings example which \n% has an organization, a publisher, and two addresses (the conference \n% location and the publisher's address), though I cheated a bit by \n% putting the conference location and month as part of the title field; \n% I feel that in this case the conference location and month can be\n% considered as part of the title, and that adding a location field \n% is not justified. Note also that a location field is not standard, \n% so entries made with this field would not port nicely to other styles. \n% However, if authors feel that there's a need for a location field \n% then tell me and I'll see what I can do.\n%\n% The file also produces to my satisfaction all the bibliographical \n% entries in my recent (joint) submission to CL (this was the original \n% motivation for creating the file). I also tested it by running it\n% on a larger set of entries and eyeballing the results. There may of\n% course still be errors, especially with combinations of fields that\n% are not that common, or with cross-references (which I seldom use). \n% If you find such errors please write to me. \n% \n% I hope people find this file useful. Please email me with comments \n% and suggestions.\n% \n% Ron Artstein\n% artstein [at] essex.ac.uk\n% August 22, 2005.\n%\n% Some technical notes.\n%\n% This file is based on a file generated with the package \n% by Patrick W. Daly (see selected options below), which was then \n% manually customized to conform with certain CL requirements which\n% cannot be met by . Departures from the generated file \n% include:\n%\n% Function inbook: moved publisher and address to the end; moved \n% edition after title; replaced function format.chapter.pages by \n% new function format.chapter to output chapter without pages.\n% \n% Function inproceedings: moved publisher and address to the end;\n% replaced function format.in.ed.booktitle by new function \n% format.in.booktitle to output the proceedings title without \n% the editor.\n% \n% Functions book, incollection, manual: moved edition after title.\n%\n% Function mastersthesis: formatted title as for articles (unlike \n% phdthesis which is formatted as book) and added month.\n% \n% Function proceedings: added new.sentence between organization and \n% publisher when both are present.\n% \n% Function format.lab.names: modified so that it gives all the\n% authors' surnames for in-text citations for one, two and three\n% authors and only uses \"et. al\" for works with four authors or more\n% (thanks to Ken Shan for convincing me to go through the trouble of \n% modifying this function rather than using unreliable hacks).\n%\n% Changes: \n%\n% 2006-10-27: Changed function reverse.pass so that the extra label is\n% enclosed in parentheses when the year field ends in an uppercase or\n% lowercase letter (change modeled after Uli Sauerland's modification\n% of nals.bst). RA.\n%\n%\n% The preamble of the generated file begins below:\n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n%%\n%% This is file `compling.bst',\n%% generated with the docstrip utility.\n%%\n%% The original source files were:\n%%\n%% merlin.mbs (with options: `ay,nat,vonx,nm-revv1,jnrlst,keyxyr,blkyear,dt-beg,yr-per,note-yr,num-xser,pre-pub,xedn,nfss')\n%% ----------------------------------------\n%% *** Intended for the journal Computational Linguistics ***\n%% \n%% Copyright 1994-2002 Patrick W Daly\n % ===============================================================\n % IMPORTANT NOTICE:\n % This bibliographic style (bst) file has been generated from one or\n % more master bibliographic style (mbs) files, listed above.\n %\n % This generated file can be redistributed and/or modified under the terms\n % of the LaTeX Project Public License Distributed from CTAN\n % archives in directory macros/latex/base/lppl.txt; either\n % version 1 of the License, or any later version.\n % ===============================================================\n % Name and version information of the main mbs file:\n % \\ProvidesFile{merlin.mbs}[2002/10/21 4.05 (PWD, AO, DPC)]\n % For use with BibTeX version 0.99a or later\n %-------------------------------------------------------------------\n % This bibliography style file is intended for texts in ENGLISH\n % This is an author-year citation style bibliography. As such, it is\n % non-standard LaTeX, and requires a special package file to function properly.\n % Such a package is natbib.sty by Patrick W. Daly\n % The form of the \\bibitem entries is\n % \\bibitem[Jones et al.(1990)]{key}...\n % \\bibitem[Jones et al.(1990)Jones, Baker, and Smith]{key}...\n % The essential feature is that the label (the part in brackets) consists\n % of the author names, as they should appear in the citation, with the year\n % in parentheses following. There must be no space before the opening\n % parenthesis!\n % With natbib v5.3, a full list of authors may also follow the year.\n % In natbib.sty, it is possible to define the type of enclosures that is\n % really wanted (brackets or parentheses), but in either case, there must\n % be parentheses in the label.\n % The \\cite command functions as follows:\n % \\citet{key} ==>> Jones et al. (1990)\n % \\citet*{key} ==>> Jones, Baker, and Smith (1990)\n % \\citep{key} ==>> (Jones et al., 1990)\n % \\citep*{key} ==>> (Jones, Baker, and Smith, 1990)\n % \\citep[chap. 2]{key} ==>> (Jones et al., 1990, chap. 2)\n % \\citep[e.g.][]{key} ==>> (e.g. Jones et al., 1990)\n % \\citep[e.g.][p. 32]{key} ==>> (e.g. Jones et al., p. 32)\n % \\citeauthor{key} ==>> Jones et al.\n % \\citeauthor*{key} ==>> Jones, Baker, and Smith\n % \\citeyear{key} ==>> 1990\n %---------------------------------------------------------------------\n\nENTRY\n { address\n author\n booktitle\n chapter\n edition\n editor\n howpublished\n institution\n journal\n key\n month\n note\n number\n organization\n pages\n publisher\n school\n series\n title\n type\n volume\n year\n eprint % urlbst\n doi % urlbst\n pubmed % urlbst\n url % urlbst\n lastchecked % urlbst\n }\n {}\n { label extra.label sort.label short.list }\nINTEGERS { output.state before.all mid.sentence after.sentence after.block }\n% urlbst...\n% urlbst constants and state variables\nSTRINGS { urlintro\n eprinturl eprintprefix doiprefix doiurl pubmedprefix pubmedurl\n citedstring onlinestring linktextstring\n openinlinelink closeinlinelink }\nINTEGERS { hrefform inlinelinks makeinlinelink\n addeprints adddoiresolver addpubmedresolver }\nFUNCTION {init.urlbst.variables}\n{\n % The following constants may be adjusted by hand, if desired\n\n % The first set allow you to enable or disable certain functionality.\n #1 'addeprints := % 0=no eprints; 1=include eprints\n #1 'adddoiresolver := % 0=no DOI resolver; 1=include it\n #1 'addpubmedresolver := % 0=no PUBMED resolver; 1=include it\n #2 'hrefform := % 0=no crossrefs; 1=hypertex xrefs; 2=hyperref refs\n #1 'inlinelinks := % 0=URLs explicit; 1=URLs attached to titles\n\n % String constants, which you _might_ want to tweak.\n \"URL: \" 'urlintro := % prefix before URL; typically \"Available from:\" or \"URL\":\n \"online\" 'onlinestring := % indication that resource is online; typically \"online\"\n \"cited \" 'citedstring := % indicator of citation date; typically \"cited \"\n \"[link]\" 'linktextstring := % dummy link text; typically \"[link]\"\n \"http://arxiv.org/abs/\" 'eprinturl := % prefix to make URL from eprint ref\n \"arXiv:\" 'eprintprefix := % text prefix printed before eprint ref; typically \"arXiv:\"\n \"https://doi.org/\" 'doiurl := % prefix to make URL from DOI\n \"doi:\" 'doiprefix := % text prefix printed before DOI ref; typically \"doi:\"\n \"http://www.ncbi.nlm.nih.gov/pubmed/\" 'pubmedurl := % prefix to make URL from PUBMED\n \"PMID:\" 'pubmedprefix := % text prefix printed before PUBMED ref; typically \"PMID:\"\n\n % The following are internal state variables, not configuration constants,\n % so they shouldn't be fiddled with.\n #0 'makeinlinelink := % state variable managed by possibly.setup.inlinelink\n \"\" 'openinlinelink := % ditto\n \"\" 'closeinlinelink := % ditto\n}\nINTEGERS { \n bracket.state\n outside.brackets\n open.brackets\n within.brackets\n close.brackets\n}\n% ...urlbst to here\nFUNCTION {init.state.consts}\n{ #0 'outside.brackets := % urlbst...\n #1 'open.brackets :=\n #2 'within.brackets :=\n #3 'close.brackets := % ...urlbst to here\n\n #0 'before.all :=\n #1 'mid.sentence :=\n #2 'after.sentence :=\n #3 'after.block :=\n}\nSTRINGS { s t}\n% urlbst\nFUNCTION {output.nonnull.original}\n{ 's :=\n output.state mid.sentence =\n { \", \" * write$ }\n { output.state after.block =\n { add.period$ write$\n newline$\n \"\\newblock \" write$\n }\n { output.state before.all =\n 'write$\n { add.period$ \" \" * write$ }\n if$\n }\n if$\n mid.sentence 'output.state :=\n }\n if$\n s\n}\n\n% urlbst...\n% The following three functions are for handling inlinelink. They wrap\n% a block of text which is potentially output with write$ by multiple\n% other functions, so we don't know the content a priori.\n% They communicate between each other using the variables makeinlinelink\n% (which is true if a link should be made), and closeinlinelink (which holds\n% the string which should close any current link. They can be called\n% at any time, but start.inlinelink will be a no-op unless something has\n% previously set makeinlinelink true, and the two ...end.inlinelink functions\n% will only do their stuff if start.inlinelink has previously set\n% closeinlinelink to be non-empty.\n% (thanks to 'ijvm' for suggested code here)\nFUNCTION {uand}\n{ 'skip$ { pop$ #0 } if$ } % 'and' (which isn't defined at this point in the file)\nFUNCTION {possibly.setup.inlinelink}\n{ makeinlinelink hrefform #0 > uand\n { doi empty$ adddoiresolver uand\n { pubmed empty$ addpubmedresolver uand\n { eprint empty$ addeprints uand\n { url empty$\n { \"\" }\n { url }\n if$ }\n { eprinturl eprint * }\n if$ }\n { pubmedurl pubmed * }\n if$ }\n { doiurl doi * }\n if$\n % an appropriately-formatted URL is now on the stack\n hrefform #1 = % hypertex\n { \"\\special {html: }{\" * 'openinlinelink :=\n \"\\special {html:}\" 'closeinlinelink := }\n { \"\\href {\" swap$ * \"} {\" * 'openinlinelink := % hrefform=#2 -- hyperref\n % the space between \"} {\" matters: a URL of just the right length can cause \"\\% newline em\"\n \"}\" 'closeinlinelink := }\n if$\n #0 'makeinlinelink :=\n }\n 'skip$\n if$ % makeinlinelink\n}\nFUNCTION {add.inlinelink}\n{ openinlinelink empty$\n 'skip$\n { openinlinelink swap$ * closeinlinelink *\n \"\" 'openinlinelink :=\n }\n if$\n}\nFUNCTION {output.nonnull}\n{ % Save the thing we've been asked to output\n 's :=\n % If the bracket-state is close.brackets, then add a close-bracket to\n % what is currently at the top of the stack, and set bracket.state\n % to outside.brackets\n bracket.state close.brackets =\n { \"]\" *\n outside.brackets 'bracket.state :=\n }\n 'skip$\n if$\n bracket.state outside.brackets =\n { % We're outside all brackets -- this is the normal situation.\n % Write out what's currently at the top of the stack, using the\n % original output.nonnull function.\n s\n add.inlinelink\n output.nonnull.original % invoke the original output.nonnull\n }\n { % Still in brackets. Add open-bracket or (continuation) comma, add the\n % new text (in s) to the top of the stack, and move to the close-brackets\n % state, ready for next time (unless inbrackets resets it). If we come\n % into this branch, then output.state is carefully undisturbed.\n bracket.state open.brackets =\n { \" [\" * }\n { \", \" * } % bracket.state will be within.brackets\n if$ \n s * \n close.brackets 'bracket.state :=\n }\n if$\n}\n\n% Call this function just before adding something which should be presented in \n% brackets. bracket.state is handled specially within output.nonnull.\nFUNCTION {inbrackets}\n{ bracket.state close.brackets =\n { within.brackets 'bracket.state := } % reset the state: not open nor closed\n { open.brackets 'bracket.state := }\n if$\n}\n\nFUNCTION {format.lastchecked}\n{ lastchecked empty$\n { \"\" }\n { inbrackets citedstring lastchecked * }\n if$\n}\n% ...urlbst to here\nFUNCTION {output}\n{ duplicate$ empty$\n 'pop$\n 'output.nonnull\n if$\n}\nFUNCTION {output.check}\n{ 't :=\n duplicate$ empty$\n { pop$ \"empty \" t * \" in \" * cite$ * warning$ }\n 'output.nonnull\n if$\n}\nFUNCTION {fin.entry.original} % urlbst (renamed from fin.entry, so it can be wrapped below)\n{ add.period$\n write$\n newline$\n}\n\nFUNCTION {new.block}\n{ output.state before.all =\n 'skip$\n { after.block 'output.state := }\n if$\n}\nFUNCTION {new.sentence}\n{ output.state after.block =\n 'skip$\n { output.state before.all =\n 'skip$\n { after.sentence 'output.state := }\n if$\n }\n if$\n}\nFUNCTION {add.blank}\n{ \" \" * before.all 'output.state :=\n}\n\nFUNCTION {date.block}\n{\n new.block\n}\n\nFUNCTION {not}\n{ { #0 }\n { #1 }\n if$\n}\nFUNCTION {and}\n{ 'skip$\n { pop$ #0 }\n if$\n}\nFUNCTION {or}\n{ { pop$ #1 }\n 'skip$\n if$\n}\nFUNCTION {new.block.checkb}\n{ empty$\n swap$ empty$\n and\n 'skip$\n 'new.block\n if$\n}\nFUNCTION {field.or.null}\n{ duplicate$ empty$\n { pop$ \"\" }\n 'skip$\n if$\n}\nFUNCTION {emphasize}\n{ duplicate$ empty$\n { pop$ \"\" }\n { \"\\emph{\" swap$ * \"}\" * }\n if$\n}\nFUNCTION {tie.or.space.prefix}\n{ duplicate$ text.length$ #3 <\n { \"~\" }\n { \" \" }\n if$\n swap$\n}\n\nFUNCTION {capitalize}\n{ \"u\" change.case$ \"t\" change.case$ }\n\nFUNCTION {space.word}\n{ \" \" swap$ * \" \" * }\n % Here are the language-specific definitions for explicit words.\n % Each function has a name bbl.xxx where xxx is the English word.\n % The language selected here is ENGLISH\nFUNCTION {bbl.and}\n{ \"and\"}\n\nFUNCTION {bbl.etal}\n{ \"et~al.\" }\n\nFUNCTION {bbl.editors}\n{ \"editors\" }\n\nFUNCTION {bbl.editor}\n{ \"editor\" }\n\nFUNCTION {bbl.edby}\n{ \"edited by\" }\n\nFUNCTION {bbl.edition}\n{ \"edition\" }\n\nFUNCTION {bbl.volume}\n{ \"volume\" }\n\nFUNCTION {bbl.of}\n{ \"of\" }\n\nFUNCTION {bbl.number}\n{ \"number\" }\n\nFUNCTION {bbl.nr}\n{ \"no.\" }\n\nFUNCTION {bbl.in}\n{ \"in\" }\n\nFUNCTION {bbl.pages}\n{ \"pages\" }\n\nFUNCTION {bbl.page}\n{ \"page\" }\n\nFUNCTION {bbl.chapter}\n{ \"chapter\" }\n\nFUNCTION {bbl.techrep}\n{ \"Technical Report\" }\n\nFUNCTION {bbl.mthesis}\n{ \"Master's thesis\" }\n\nFUNCTION {bbl.phdthesis}\n{ \"Ph.D. thesis\" }\n\nMACRO {jan} {\"January\"}\n\nMACRO {feb} {\"February\"}\n\nMACRO {mar} {\"March\"}\n\nMACRO {apr} {\"April\"}\n\nMACRO {may} {\"May\"}\n\nMACRO {jun} {\"June\"}\n\nMACRO {jul} {\"July\"}\n\nMACRO {aug} {\"August\"}\n\nMACRO {sep} {\"September\"}\n\nMACRO {oct} {\"October\"}\n\nMACRO {nov} {\"November\"}\n\nMACRO {dec} {\"December\"}\n\nMACRO {acmcs} {\"ACM Computing Surveys\"}\n\nMACRO {acta} {\"Acta Informatica\"}\n\nMACRO {cacm} {\"Communications of the ACM\"}\n\nMACRO {ibmjrd} {\"IBM Journal of Research and Development\"}\n\nMACRO {ibmsj} {\"IBM Systems Journal\"}\n\nMACRO {ieeese} {\"IEEE Transactions on Software Engineering\"}\n\nMACRO {ieeetc} {\"IEEE Transactions on Computers\"}\n\nMACRO {ieeetcad}\n {\"IEEE Transactions on Computer-Aided Design of Integrated Circuits\"}\n\nMACRO {ipl} {\"Information Processing Letters\"}\n\nMACRO {jacm} {\"Journal of the ACM\"}\n\nMACRO {jcss} {\"Journal of Computer and System Sciences\"}\n\nMACRO {scp} {\"Science of Computer Programming\"}\n\nMACRO {sicomp} {\"SIAM Journal on Computing\"}\n\nMACRO {tocs} {\"ACM Transactions on Computer Systems\"}\n\nMACRO {tods} {\"ACM Transactions on Database Systems\"}\n\nMACRO {tog} {\"ACM Transactions on Graphics\"}\n\nMACRO {toms} {\"ACM Transactions on Mathematical Software\"}\n\nMACRO {toois} {\"ACM Transactions on Office Information Systems\"}\n\nMACRO {toplas} {\"ACM Transactions on Programming Languages and Systems\"}\n\nMACRO {tcs} {\"Theoretical Computer Science\"}\nFUNCTION {bibinfo.check}\n{ swap$\n duplicate$ missing$\n {\n pop$ pop$\n \"\"\n }\n { duplicate$ empty$\n {\n swap$ pop$\n }\n { swap$\n pop$\n }\n if$\n }\n if$\n}\nFUNCTION {bibinfo.warn}\n{ swap$\n duplicate$ missing$\n {\n swap$ \"missing \" swap$ * \" in \" * cite$ * warning$ pop$\n \"\"\n }\n { duplicate$ empty$\n {\n swap$ \"empty \" swap$ * \" in \" * cite$ * warning$\n }\n { swap$\n pop$\n }\n if$\n }\n if$\n}\nSTRINGS { bibinfo}\nINTEGERS { nameptr namesleft numnames }\n\nFUNCTION {format.names}\n{ 'bibinfo :=\n duplicate$ empty$ 'skip$ {\n 's :=\n \"\" 't :=\n #1 'nameptr :=\n s num.names$ 'numnames :=\n numnames 'namesleft :=\n { namesleft #0 > }\n { s nameptr\n duplicate$ #1 >\n { \"{ff~}{vv~}{ll}{, jj}\" }\n { \"{ff~}{vv~}{ll}{, jj}\" }\t% first name first for first author \n% { \"{vv~}{ll}{, ff}{, jj}\" }\t% last name first for first author\n if$\n format.name$\n bibinfo bibinfo.check\n 't :=\n nameptr #1 >\n {\n namesleft #1 >\n { \", \" * t * }\n {\n numnames #2 >\n { \",\" * }\n 'skip$\n if$\n s nameptr \"{ll}\" format.name$ duplicate$ \"others\" =\n { 't := }\n { pop$ }\n if$\n t \"others\" =\n {\n \" \" * bbl.etal *\n }\n {\n bbl.and\n space.word * t *\n }\n if$\n }\n if$\n }\n 't\n if$\n nameptr #1 + 'nameptr :=\n namesleft #1 - 'namesleft :=\n }\n while$\n } if$\n}\nFUNCTION {format.names.ed}\n{\n 'bibinfo :=\n duplicate$ empty$ 'skip$ {\n 's :=\n \"\" 't :=\n #1 'nameptr :=\n s num.names$ 'numnames :=\n numnames 'namesleft :=\n { namesleft #0 > }\n { s nameptr\n \"{ff~}{vv~}{ll}{, jj}\"\n format.name$\n bibinfo bibinfo.check\n 't :=\n nameptr #1 >\n {\n namesleft #1 >\n { \", \" * t * }\n {\n numnames #2 >\n { \",\" * }\n 'skip$\n if$\n s nameptr \"{ll}\" format.name$ duplicate$ \"others\" =\n { 't := }\n { pop$ }\n if$\n t \"others\" =\n {\n\n \" \" * bbl.etal *\n }\n {\n bbl.and\n space.word * t *\n }\n if$\n }\n if$\n }\n 't\n if$\n nameptr #1 + 'nameptr :=\n namesleft #1 - 'namesleft :=\n }\n while$\n } if$\n}\nFUNCTION {format.key}\n{ empty$\n { key field.or.null }\n { \"\" }\n if$\n}\n\nFUNCTION {format.authors}\n{ author \"author\" format.names\n}\nFUNCTION {get.bbl.editor}\n{ editor num.names$ #1 > 'bbl.editors 'bbl.editor if$ }\n\nFUNCTION {format.editors}\n{ editor \"editor\" format.names duplicate$ empty$ 'skip$\n {\n \",\" *\n \" \" *\n get.bbl.editor\n *\n }\n if$\n}\nFUNCTION {format.note}\n{\n note empty$\n { \"\" }\n { note #1 #1 substring$\n duplicate$ \"{\" =\n 'skip$\n { output.state mid.sentence =\n { \"l\" }\n { \"u\" }\n if$\n change.case$\n }\n if$\n note #2 global.max$ substring$ * \"note\" bibinfo.check\n }\n if$\n}\n\nFUNCTION {format.title}\n{ title\n duplicate$ empty$ 'skip$\n { \"t\" change.case$ }\n if$\n \"title\" bibinfo.check\n}\nFUNCTION {format.full.names}\n{'s :=\n \"\" 't :=\n #1 'nameptr :=\n s num.names$ 'numnames :=\n numnames 'namesleft :=\n { namesleft #0 > }\n { s nameptr\n \"{vv~}{ll}\" format.name$\n 't :=\n nameptr #1 >\n {\n namesleft #1 >\n { \", \" * t * }\n {\n s nameptr \"{ll}\" format.name$ duplicate$ \"others\" =\n { 't := }\n { pop$ }\n if$\n t \"others\" =\n {\n \" \" * bbl.etal *\n }\n {\n numnames #2 >\n { \",\" * }\n 'skip$\n if$\n bbl.and\n space.word * t *\n }\n if$\n }\n if$\n }\n 't\n if$\n nameptr #1 + 'nameptr :=\n namesleft #1 - 'namesleft :=\n }\n while$\n}\n\nFUNCTION {author.editor.key.full}\n{ author empty$\n { editor empty$\n { key empty$\n { cite$ #1 #3 substring$ }\n 'key\n if$\n }\n { editor format.full.names }\n if$\n }\n { author format.full.names }\n if$\n}\n\nFUNCTION {author.key.full}\n{ author empty$\n { key empty$\n { cite$ #1 #3 substring$ }\n 'key\n if$\n }\n { author format.full.names }\n if$\n}\n\nFUNCTION {editor.key.full}\n{ editor empty$\n { key empty$\n { cite$ #1 #3 substring$ }\n 'key\n if$\n }\n { editor format.full.names }\n if$\n}\n\nFUNCTION {make.full.names}\n{ type$ \"book\" =\n type$ \"inbook\" =\n or\n 'author.editor.key.full\n { type$ \"proceedings\" =\n 'editor.key.full\n 'author.key.full\n if$\n }\n if$\n}\n\nFUNCTION {output.bibitem.original} % urlbst (renamed from output.bibitem, so it can be wrapped below)\n{ newline$\n \"\\bibitem[{\" write$\n label write$\n \")\" make.full.names duplicate$ short.list =\n { pop$ }\n { * }\n if$\n \"}]{\" * write$\n cite$ write$\n \"}\" write$\n newline$\n \"\"\n before.all 'output.state :=\n}\n\nFUNCTION {n.dashify}\n{\n 't :=\n \"\"\n { t empty$ not }\n { t #1 #1 substring$ \"-\" =\n { t #1 #2 substring$ \"--\" = not\n { \"--\" *\n t #2 global.max$ substring$ 't :=\n }\n { { t #1 #1 substring$ \"-\" = }\n { \"-\" *\n t #2 global.max$ substring$ 't :=\n }\n while$\n }\n if$\n }\n { t #1 #1 substring$ *\n t #2 global.max$ substring$ 't :=\n }\n if$\n }\n while$\n}\n\nFUNCTION {word.in}\n{ bbl.in capitalize\n \" \" * }\n\nFUNCTION {format.date}\n{ year \"year\" bibinfo.check duplicate$ empty$\n {\n }\n 'skip$\n if$\n extra.label *\n before.all 'output.state :=\n after.sentence 'output.state :=\n}\nFUNCTION {format.btitle}\n{ title \"title\" bibinfo.check\n duplicate$ empty$ 'skip$\n {\n emphasize\n }\n if$\n}\nFUNCTION {either.or.check}\n{ empty$\n 'pop$\n { \"can't use both \" swap$ * \" fields in \" * cite$ * warning$ }\n if$\n}\nFUNCTION {format.bvolume}\n{ volume empty$\n { \"\" }\n { bbl.volume volume tie.or.space.prefix\n \"volume\" bibinfo.check * *\n series \"series\" bibinfo.check\n duplicate$ empty$ 'pop$\n { swap$ bbl.of space.word * swap$\n emphasize * }\n if$\n \"volume and number\" number either.or.check\n }\n if$\n}\nFUNCTION {format.number.series}\n{ volume empty$\n { number empty$\n { series field.or.null }\n { series empty$\n { number \"number\" bibinfo.check }\n { output.state mid.sentence =\n { bbl.number }\n { bbl.number capitalize }\n if$\n number tie.or.space.prefix \"number\" bibinfo.check * *\n bbl.in space.word *\n series \"series\" bibinfo.check *\n }\n if$\n }\n if$\n }\n { \"\" }\n if$\n}\n\nFUNCTION {format.edition}\n{ edition duplicate$ empty$ 'skip$\n {\n output.state mid.sentence =\n { \"l\" }\n { \"t\" }\n if$ change.case$\n \"edition\" bibinfo.check\n \" \" * bbl.edition *\n }\n if$\n}\nINTEGERS { multiresult }\nFUNCTION {multi.page.check}\n{ 't :=\n #0 'multiresult :=\n { multiresult not\n t empty$ not\n and\n }\n { t #1 #1 substring$\n duplicate$ \"-\" =\n swap$ duplicate$ \",\" =\n swap$ \"+\" =\n or or\n { #1 'multiresult := }\n { t #2 global.max$ substring$ 't := }\n if$\n }\n while$\n multiresult\n}\nFUNCTION {format.pages}\n{ pages duplicate$ empty$ 'skip$\n { duplicate$ multi.page.check\n {\n bbl.pages swap$\n n.dashify\n }\n {\n bbl.page swap$\n }\n if$\n tie.or.space.prefix\n \"pages\" bibinfo.check\n * *\n }\n if$\n}\nFUNCTION {format.journal.pages}\n{ pages duplicate$ empty$ 'pop$\n { swap$ duplicate$ empty$\n { pop$ pop$ format.pages }\n {\n \":\" *\n swap$\n n.dashify\n \"pages\" bibinfo.check\n *\n }\n if$\n }\n if$\n}\nFUNCTION {format.vol.num.pages}\n{ volume field.or.null\n duplicate$ empty$ 'skip$\n {\n \"volume\" bibinfo.check\n }\n if$\n number \"number\" bibinfo.check duplicate$ empty$ 'skip$\n {\n swap$ duplicate$ empty$\n { \"there's a number but no volume in \" cite$ * warning$ }\n 'skip$\n if$\n swap$\n \"(\" swap$ * \")\" *\n }\n if$ *\n format.journal.pages\n}\n\nFUNCTION {format.chapter}\n{ chapter empty$\n %'skip$ %% SC\n { \"\" }\n { type empty$\n { bbl.chapter }\n { type \"l\" change.case$\n \"type\" bibinfo.check\n }\n if$\n chapter tie.or.space.prefix\n \"chapter\" bibinfo.check\n * *\n }\n if$\n}\n\nFUNCTION {format.chapter.pages}\n{ chapter empty$\n 'format.pages\n { type empty$\n { bbl.chapter }\n { type \"l\" change.case$\n \"type\" bibinfo.check\n }\n if$\n chapter tie.or.space.prefix\n \"chapter\" bibinfo.check\n * *\n pages empty$\n 'skip$\n { \", \" * format.pages * }\n if$\n }\n if$\n}\n\nFUNCTION {format.booktitle}\n{\n booktitle \"booktitle\" bibinfo.check\n emphasize\n}\nFUNCTION {format.in.booktitle}\n{ format.booktitle duplicate$ empty$ 'skip$\n {\n word.in swap$ *\n }\n if$\n}\nFUNCTION {format.in.ed.booktitle}\n{ format.booktitle duplicate$ empty$ 'skip$\n {\n editor \"editor\" format.names.ed duplicate$ empty$ 'pop$\n {\n \",\" *\n \" \" *\n get.bbl.editor\n \", \" *\n * swap$\n * }\n if$\n word.in swap$ *\n }\n if$\n}\nFUNCTION {format.thesis.type}\n{ type duplicate$ empty$\n 'pop$\n { swap$ pop$\n \"t\" change.case$ \"type\" bibinfo.check\n }\n if$\n}\nFUNCTION {format.tr.number}\n{ number \"number\" bibinfo.check\n type duplicate$ empty$\n { pop$ bbl.techrep }\n 'skip$\n if$\n \"type\" bibinfo.check\n swap$ duplicate$ empty$\n { pop$ \"t\" change.case$ }\n { tie.or.space.prefix * * }\n if$\n}\nFUNCTION {format.article.crossref}\n{\n word.in\n \" \\cite{\" * crossref * \"}\" *\n}\nFUNCTION {format.book.crossref}\n{ volume duplicate$ empty$\n { \"empty volume in \" cite$ * \"'s crossref of \" * crossref * warning$\n pop$ word.in\n }\n { bbl.volume\n capitalize\n swap$ tie.or.space.prefix \"volume\" bibinfo.check * * bbl.of space.word *\n }\n if$\n \" \\cite{\" * crossref * \"}\" *\n}\nFUNCTION {format.incoll.inproc.crossref}\n{\n word.in\n \" \\cite{\" * crossref * \"}\" *\n}\nFUNCTION {format.org.or.pub}\n{ 't :=\n \"\"\n address empty$ t empty$ and\n 'skip$\n {\n t empty$\n { address \"address\" bibinfo.check *\n }\n { t *\n address empty$\n 'skip$\n { \", \" * address \"address\" bibinfo.check * }\n if$\n }\n if$\n }\n if$\n}\nFUNCTION {format.publisher.address}\n{ publisher \"publisher\" bibinfo.warn format.org.or.pub\n}\n\nFUNCTION {format.organization.address}\n{ organization \"organization\" bibinfo.check format.org.or.pub\n}\n\n% urlbst...\n% Functions for making hypertext links.\n% In all cases, the stack has (link-text href-url)\n%\n% make 'null' specials\nFUNCTION {make.href.null}\n{\n pop$\n}\n% make hypertex specials\nFUNCTION {make.href.hypertex}\n{ \n \"\\special {html: }\" * swap$ *\n \"\\special {html:}\" *\n}\n% make hyperref specials\nFUNCTION {make.href.hyperref}\n{ \n \"\\href {\" swap$ * \"} {\\path{\" * swap$ * \"}}\" *\n}\nFUNCTION {make.href}\n{ hrefform #2 =\n 'make.href.hyperref % hrefform = 2\n { hrefform #1 =\n 'make.href.hypertex % hrefform = 1\n 'make.href.null % hrefform = 0 (or anything else)\n if$\n }\n if$\n}\n\n% If inlinelinks is true, then format.url should be a no-op, since it's\n% (a) redundant, and (b) could end up as a link-within-a-link.\nFUNCTION {format.url}\n{ inlinelinks #1 = url empty$ or\n { \"\" }\n { hrefform #1 =\n { % special case -- add HyperTeX specials\n urlintro \"\\url{\" url * \"}\" * url make.href.hypertex * }\n { urlintro \"\\url{\" * url * \"}\" * }\n if$\n }\n if$\n}\n\nFUNCTION {format.eprint}\n{ eprint empty$\n { \"\" }\n { eprintprefix eprint * eprinturl eprint * make.href }\n if$\n}\n\nFUNCTION {format.doi}\n{ doi empty$\n { \"\" }\n { doiprefix doi * doiurl doi * make.href }\n if$\n}\n\nFUNCTION {format.pubmed}\n{ pubmed empty$\n { \"\" }\n { pubmedprefix pubmed * pubmedurl pubmed * make.href }\n if$\n}\n\n% Output a URL. We can't use the more normal idiom (something like\n% `format.url output'), because the `inbrackets' within\n% format.lastchecked applies to everything between calls to `output',\n% so that `format.url format.lastchecked * output' ends up with both\n% the URL and the lastchecked in brackets.\nFUNCTION {output.url}\n{ url empty$\n 'skip$ \n { new.block \n format.url output\n format.lastchecked output \n }\n if$\n}\n\nFUNCTION {output.web.refs}\n{\n new.block\n inlinelinks\n 'skip$ % links were inline -- don't repeat them\n {\n output.url\n addeprints eprint empty$ not and\n { format.eprint output.nonnull }\n 'skip$\n if$\n adddoiresolver doi empty$ not and\n { format.doi output.nonnull }\n 'skip$\n if$\n addpubmedresolver pubmed empty$ not and\n { format.pubmed output.nonnull }\n 'skip$\n if$\n }\n if$\n}\n\n% Wrapper for output.bibitem.original.\n% If the URL field is not empty, set makeinlinelink to be true,\n% so that an inline link will be started at the next opportunity\nFUNCTION {output.bibitem}\n{ outside.brackets 'bracket.state :=\n output.bibitem.original\n inlinelinks url empty$ not doi empty$ not or pubmed empty$ not or eprint empty$ not or and\n { #1 'makeinlinelink := }\n { #0 'makeinlinelink := }\n if$\n}\n\n% Wrapper for fin.entry.original\nFUNCTION {fin.entry}\n{ output.web.refs % urlbst\n makeinlinelink % ooops, it appears we didn't have a title for inlinelink\n { possibly.setup.inlinelink % add some artificial link text here, as a fallback\n linktextstring output.nonnull }\n 'skip$\n if$\n bracket.state close.brackets = % urlbst\n { \"]\" * }\n 'skip$\n if$\n fin.entry.original\n}\n\n% Webpage entry type.\n% Title and url fields required;\n% author, note, year, month, and lastchecked fields optional\n% See references \n% ISO 690-2 http://www.nlc-bnc.ca/iso/tc46sc9/standard/690-2e.htm\n% http://www.classroom.net/classroom/CitingNetResources.html\n% http://neal.ctstateu.edu/history/cite.html\n% http://www.cas.usf.edu/english/walker/mla.html\n% for citation formats for web pages.\nFUNCTION {webpage}\n{ output.bibitem\n author empty$\n { editor empty$\n 'skip$ % author and editor both optional\n { format.editors output.nonnull }\n if$\n }\n { editor empty$\n { format.authors output.nonnull }\n { \"can't use both author and editor fields in \" cite$ * warning$ }\n if$\n }\n if$\n new.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$\n format.title \"title\" output.check\n inbrackets onlinestring output\n new.block\n year empty$\n 'skip$\n { format.date \"year\" output.check }\n if$\n % We don't need to output the URL details ('lastchecked' and 'url'),\n % because fin.entry does that for us, using output.web.refs. The only\n % reason we would want to put them here is if we were to decide that\n % they should go in front of the rather miscellaneous information in 'note'.\n new.block\n note output\n fin.entry\n}\n% ...urlbst to here\n\n\nFUNCTION {article}\n{ output.bibitem\n format.authors \"author\" output.check\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.title \"title\" output.check\n new.block\n crossref missing$\n {\n journal\n \"journal\" bibinfo.check\n emphasize\n \"journal\" output.check\n possibly.setup.inlinelink format.vol.num.pages output% urlbst\n }\n { format.article.crossref output.nonnull\n format.pages output\n }\n if$\n new.block\n format.note output\n fin.entry\n}\nFUNCTION {book}\n{ output.bibitem\n author empty$\n { format.editors \"author and editor\" output.check\n editor format.key output\n }\n { format.authors output.nonnull\n crossref missing$\n { \"author and editor\" editor either.or.check }\n 'skip$\n if$\n }\n if$\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.btitle \"title\" output.check\n format.edition output\n crossref missing$\n { format.bvolume output\n new.block\n format.number.series output\n new.sentence\n format.publisher.address output\n }\n {\n new.block\n format.book.crossref output.nonnull\n }\n if$\n new.block\n format.note output\n fin.entry\n}\nFUNCTION {booklet}\n{ output.bibitem\n format.authors output\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.title \"title\" output.check\n new.block\n howpublished \"howpublished\" bibinfo.check output\n address \"address\" bibinfo.check output\n new.block\n format.note output\n fin.entry\n}\n\nFUNCTION {inbook}\n{ output.bibitem\n author empty$\n { format.editors \"author and editor\" output.check\n editor format.key output\n }\n { format.authors output.nonnull\n crossref missing$\n { \"author and editor\" editor either.or.check }\n 'skip$\n if$\n }\n if$\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.btitle \"title\" output.check\n format.edition output\n crossref missing$\n {\n format.bvolume output\n format.number.series output\n format.chapter \"chapter\" output.check\n new.sentence\n format.publisher.address output\n new.block\n }\n {\n format.chapter \"chapter\" output.check\n new.block\n format.book.crossref output.nonnull\n }\n if$\n new.block\n format.note output\n fin.entry\n}\n\nFUNCTION {incollection}\n{ output.bibitem\n format.authors \"author\" output.check\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.title \"title\" output.check\n new.block\n crossref missing$\n { format.in.ed.booktitle \"booktitle\" output.check\n format.edition output\n format.bvolume output\n format.number.series output\n format.chapter.pages output\n new.sentence\n format.publisher.address output\n }\n { format.incoll.inproc.crossref output.nonnull\n format.chapter.pages output\n }\n if$\n new.block\n format.note output\n fin.entry\n}\nFUNCTION {inproceedings}\n{ output.bibitem\n format.authors \"author\" output.check\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.title \"title\" output.check\n new.block\n crossref missing$\n { format.in.booktitle \"booktitle\" output.check\n format.bvolume output\n format.number.series output\n format.pages output\n address \"address\" bibinfo.check output\n new.sentence\n organization \"organization\" bibinfo.check output\n publisher \"publisher\" bibinfo.check output\n }\n { format.incoll.inproc.crossref output.nonnull\n format.pages output\n }\n if$\n new.block\n format.note output\n fin.entry\n}\nFUNCTION {conference} { inproceedings }\nFUNCTION {manual}\n{ output.bibitem\n format.authors output\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.btitle \"title\" output.check\n format.edition output\n organization address new.block.checkb\n organization \"organization\" bibinfo.check output\n address \"address\" bibinfo.check output\n new.block\n format.note output\n fin.entry\n}\n\nFUNCTION {mastersthesis}\n{ output.bibitem\n format.authors \"author\" output.check\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.title\n \"title\" output.check\n new.block\n bbl.mthesis format.thesis.type output.nonnull\n school \"school\" bibinfo.warn output\n address \"address\" bibinfo.check output\n month \"month\" bibinfo.check output\n new.block\n format.note output\n fin.entry\n}\n\nFUNCTION {misc}\n{ output.bibitem\n format.authors output\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.title output\n new.block\n howpublished \"howpublished\" bibinfo.check output\n new.block\n format.note output\n fin.entry\n}\nFUNCTION {phdthesis}\n{ output.bibitem\n format.authors \"author\" output.check\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.btitle\n \"title\" output.check\n new.block\n bbl.phdthesis format.thesis.type output.nonnull\n school \"school\" bibinfo.warn output\n address \"address\" bibinfo.check output\n new.block\n format.note output\n fin.entry\n}\n\nFUNCTION {proceedings}\n{ output.bibitem\n format.editors output\n editor format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.btitle \"title\" output.check\n format.bvolume output\n format.number.series output\n new.sentence\n publisher empty$\n { format.organization.address output }\n { organization \"organization\" bibinfo.check output\n new.sentence\n format.publisher.address output\n }\n if$\n new.block\n format.note output\n fin.entry\n}\n\nFUNCTION {techreport}\n{ output.bibitem\n format.authors \"author\" output.check\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.title\n \"title\" output.check\n new.block\n format.tr.number output.nonnull\n institution \"institution\" bibinfo.warn output\n address \"address\" bibinfo.check output\n new.block\n format.note output\n fin.entry\n}\n\nFUNCTION {unpublished}\n{ output.bibitem\n format.authors \"author\" output.check\n author format.key output\n format.date \"year\" output.check\n date.block\n title empty$ 'skip$ 'possibly.setup.inlinelink if$ % urlbst\n format.title \"title\" output.check\n new.block\n format.note \"note\" output.check\n fin.entry\n}\n\nFUNCTION {default.type} { misc }\nREAD\nFUNCTION {sortify}\n{ purify$\n \"l\" change.case$\n}\nINTEGERS { len }\nFUNCTION {chop.word}\n{ 's :=\n 'len :=\n s #1 len substring$ =\n { s len #1 + global.max$ substring$ }\n 's\n if$\n}\nFUNCTION {format.lab.names}\n{ 's :=\n \"\" 't :=\n s #1 \"{vv~}{ll}\" format.name$\n s num.names$ duplicate$\n #2 >\n { pop$\n \" \" * bbl.etal *\n }\n { #2 <\n 'skip$\n { s #2 \"{ff }{vv }{ll}{ jj}\" format.name$ \"others\" =\n {\n \" \" * bbl.etal *\n }\n { bbl.and space.word * s #2 \"{vv~}{ll}\" format.name$\n * }\n if$\n }\n if$\n }\n if$\n}\n\nFUNCTION {author.key.label}\n{ author empty$\n { key empty$\n { cite$ #1 #3 substring$ }\n 'key\n if$\n }\n { author format.lab.names }\n if$\n}\n\nFUNCTION {author.editor.key.label}\n{ author empty$\n { editor empty$\n { key empty$\n { cite$ #1 #3 substring$ }\n 'key\n if$\n }\n { editor format.lab.names }\n if$\n }\n { author format.lab.names }\n if$\n}\n\nFUNCTION {editor.key.label}\n{ editor empty$\n { key empty$\n { cite$ #1 #3 substring$ }\n 'key\n if$\n }\n { editor format.lab.names }\n if$\n}\n\nFUNCTION {calc.short.authors}\n{ type$ \"book\" =\n type$ \"inbook\" =\n or\n 'author.editor.key.label\n { type$ \"proceedings\" =\n 'editor.key.label\n 'author.key.label\n if$\n }\n if$\n 'short.list :=\n}\n\nFUNCTION {calc.label}\n{ calc.short.authors\n short.list\n \"(\"\n *\n year duplicate$ empty$\n short.list key field.or.null = or\n { pop$ \"\" }\n 'skip$\n if$\n *\n 'label :=\n}\n\nFUNCTION {sort.format.names}\n{ 's :=\n #1 'nameptr :=\n \"\"\n s num.names$ 'numnames :=\n numnames 'namesleft :=\n { namesleft #0 > }\n { s nameptr\n \"{ll{ }}{ ff{ }}{ jj{ }}\"\n format.name$ 't :=\n nameptr #1 >\n {\n \" \" *\n namesleft #1 = t \"others\" = and\n { \"zzzzz\" * }\n { t sortify * }\n if$\n }\n { t sortify * }\n if$\n nameptr #1 + 'nameptr :=\n namesleft #1 - 'namesleft :=\n }\n while$\n}\n\nFUNCTION {sort.format.title}\n{ 't :=\n \"A \" #2\n \"An \" #3\n \"The \" #4 t chop.word\n chop.word\n chop.word\n sortify\n #1 global.max$ substring$\n}\nFUNCTION {author.sort}\n{ author empty$\n { key empty$\n { \"to sort, need author or key in \" cite$ * warning$\n \"\"\n }\n { key sortify }\n if$\n }\n { author sort.format.names }\n if$\n}\nFUNCTION {author.editor.sort}\n{ author empty$\n { editor empty$\n { key empty$\n { \"to sort, need author, editor, or key in \" cite$ * warning$\n \"\"\n }\n { key sortify }\n if$\n }\n { editor sort.format.names }\n if$\n }\n { author sort.format.names }\n if$\n}\nFUNCTION {editor.sort}\n{ editor empty$\n { key empty$\n { \"to sort, need editor or key in \" cite$ * warning$\n \"\"\n }\n { key sortify }\n if$\n }\n { editor sort.format.names }\n if$\n}\nFUNCTION {presort}\n{ calc.label\n label sortify\n \" \"\n *\n type$ \"book\" =\n type$ \"inbook\" =\n or\n 'author.editor.sort\n { type$ \"proceedings\" =\n 'editor.sort\n 'author.sort\n if$\n }\n if$\n #1 entry.max$ substring$\n 'sort.label :=\n sort.label\n *\n \" \"\n *\n title field.or.null\n sort.format.title\n *\n #1 entry.max$ substring$\n 'sort.key$ :=\n}\n\nITERATE {presort}\nSORT\nSTRINGS { last.label next.extra }\nINTEGERS { last.extra.num number.label }\nFUNCTION {initialize.extra.label.stuff}\n{ #0 int.to.chr$ 'last.label :=\n \"\" 'next.extra :=\n #0 'last.extra.num :=\n #0 'number.label :=\n}\nFUNCTION {forward.pass}\n{ last.label label =\n { last.extra.num #1 + 'last.extra.num :=\n last.extra.num int.to.chr$ 'extra.label :=\n }\n { \"a\" chr.to.int$ 'last.extra.num :=\n \"\" 'extra.label :=\n label 'last.label :=\n }\n if$\n number.label #1 + 'number.label :=\n}\nFUNCTION {reverse.pass}\n{ next.extra \"b\" =\n { \"a\" 'extra.label := }\n 'skip$\n if$\n extra.label 'next.extra :=\n extra.label\n duplicate$ empty$\n 'skip$\n { year field.or.null #-1 #1 substring$ chr.to.int$ #65 < \n { \"{\\natexlab{\" swap$ * \"}}\" * }\n { \"{(\\natexlab{\" swap$ * \"})}\" * }\n if$ }\n if$\n 'extra.label :=\n label extra.label * 'label :=\n}\nEXECUTE {initialize.extra.label.stuff}\nITERATE {forward.pass}\nREVERSE {reverse.pass}\nFUNCTION {bib.sort.order}\n{ sort.label\n \" \"\n *\n year field.or.null sortify\n *\n \" \"\n *\n title field.or.null\n sort.format.title\n *\n #1 entry.max$ substring$\n 'sort.key$ :=\n}\nITERATE {bib.sort.order}\nSORT\nFUNCTION {begin.bib}\n{ preamble$ empty$\n 'skip$\n { preamble$ write$ newline$ }\n if$\n \"\\begin{thebibliography}{\" number.label int.to.str$ * \"}\" *\n write$ newline$\n \"\\expandafter\\ifx\\csname natexlab\\endcsname\\relax\\def\\natexlab#1{#1}\\fi\"\n write$ newline$\n}\nEXECUTE {begin.bib}\nEXECUTE {init.urlbst.variables} % urlbst\nEXECUTE {init.state.consts}\nITERATE {call.type$}\nFUNCTION {end.bib}\n{ newline$\n \"\\end{thebibliography}\" write$ newline$\n}\nEXECUTE {end.bib}\n%% End of customized bst file\n%%\n%% End of file `compling.bst'.\n" } ]