The C++ Frontend
================

The PyTorch C++ frontend is a C++14 library for CPU and GPU
tensor computation, with automatic differentiation and high level building
blocks for state of the art machine learning applications.

Description
-----------

The PyTorch C++ frontend can be thought of as a C++ version of the
PyTorch Python frontend, providing automatic differentiation and various higher
level abstractions for machine learning and neural networks.  Specifically,
it consists of the following components:

+----------------------+------------------------------------------------------------------------+
| Component            | Description                                                            |
+======================+========================================================================+
| ``torch::Tensor``    | Automatically differentiable, efficient CPU and GPU enabled tensors    |
+----------------------+------------------------------------------------------------------------+
| ``torch::nn``        | A collection of composable modules for neural network modeling         |
+----------------------+------------------------------------------------------------------------+
| ``torch::optim``     | Optimization algorithms like SGD, Adam or RMSprop to train your models |
+----------------------+------------------------------------------------------------------------+
| ``torch::data``      | Datasets, data pipelines and multi-threaded, asynchronous data loader  |
+----------------------+------------------------------------------------------------------------+
| ``torch::serialize`` | A serialization API for storing and loading model checkpoints          |
+----------------------+------------------------------------------------------------------------+
| ``torch::python``    | Glue to bind your C++ models into Python                               |
+----------------------+------------------------------------------------------------------------+
| ``torch::jit``       | Pure C++ access to the TorchScript JIT compiler                        |
+----------------------+------------------------------------------------------------------------+

End-to-end example
------------------

Here is a simple, end-to-end example of defining and training a simple
neural network on the MNIST dataset:

.. code-block:: cpp

  #include <torch/torch.h>

  // Define a new Module.
  struct Net : torch::nn::Module {
    Net() {
      // Construct and register two Linear submodules.
      fc1 = register_module("fc1", torch::nn::Linear(784, 64));
      fc2 = register_module("fc2", torch::nn::Linear(64, 32));
      fc3 = register_module("fc3", torch::nn::Linear(32, 10));
    }

    // Implement the Net's algorithm.
    torch::Tensor forward(torch::Tensor x) {
      // Use one of many tensor manipulation functions.
      x = torch::relu(fc1->forward(x.reshape({x.size(0), 784})));
      x = torch::dropout(x, /*p=*/0.5, /*train=*/is_training());
      x = torch::relu(fc2->forward(x));
      x = torch::log_softmax(fc3->forward(x), /*dim=*/1);
      return x;
    }

    // Use one of many "standard library" modules.
    torch::nn::Linear fc1{nullptr}, fc2{nullptr}, fc3{nullptr};
  };

  int main() {
    // Create a new Net.
    auto net = std::make_shared<Net>();

    // Create a multi-threaded data loader for the MNIST dataset.
    auto data_loader = torch::data::make_data_loader(
        torch::data::datasets::MNIST("./data").map(
            torch::data::transforms::Stack<>()),
        /*batch_size=*/64);

    // Instantiate an SGD optimization algorithm to update our Net's parameters.
    torch::optim::SGD optimizer(net->parameters(), /*lr=*/0.01);

    for (size_t epoch = 1; epoch <= 10; ++epoch) {
      size_t batch_index = 0;
      // Iterate the data loader to yield batches from the dataset.
      for (auto& batch : *data_loader) {
        // Reset gradients.
        optimizer.zero_grad();
        // Execute the model on the input data.
        torch::Tensor prediction = net->forward(batch.data);
        // Compute a loss value to judge the prediction of our model.
        torch::Tensor loss = torch::nll_loss(prediction, batch.target);
        // Compute gradients of the loss w.r.t. the parameters of our model.
        loss.backward();
        // Update the parameters based on the calculated gradients.
        optimizer.step();
        // Output the loss and checkpoint every 100 batches.
        if (++batch_index % 100 == 0) {
          std::cout << "Epoch: " << epoch << " | Batch: " << batch_index
                    << " | Loss: " << loss.item<float>() << std::endl;
          // Serialize your model periodically as a checkpoint.
          torch::save(net, "net.pt");
        }
      }
    }
  }

To see more complete examples of using the PyTorch C++ frontend, see `the example repository
<https://github.com/pytorch/examples/tree/master/cpp>`_.

Philosophy
----------

PyTorch's C++ frontend was designed with the idea that the Python frontend is
great, and should be used when possible; but in some settings, performance and
portability requirements make the use of the Python interpreter infeasible. For
example, Python is a poor choice for low latency, high performance or
multithreaded environments, such as video games or production servers.  The
goal of the C++ frontend is to address these use cases, while not sacrificing
the user experience of the Python frontend.

As such, the C++ frontend has been written with a few philosophical goals in mind:

* **Closely model the Python frontend in its design**, naming, conventions and
  functionality.  While there may be occasional differences between the two
  frontends (e.g., where we have dropped deprecated features or fixed "warts"
  in the Python frontend), we guarantee that the effort in porting a Python model
  to C++ should lie exclusively in **translating language features**,
  not modifying functionality or behavior.

* **Prioritize flexibility and user-friendliness over micro-optimization.**
  In C++, you can often get optimal code, but at the cost of an extremely
  unfriendly user experience.  Flexibility and dynamism is at the heart of
  PyTorch, and the C++ frontend seeks to preserve this experience, in some
  cases sacrificing performance (or "hiding" performance knobs) to keep APIs
  simple and explicable.  We want researchers who don't write C++ for a living
  to be able to use our APIs.

A word of warning: Python is not necessarily slower than
C++! The Python frontend calls into C++ for almost anything computationally expensive
(especially any kind of numeric operation), and these operations will take up
the bulk of time spent in a program.  If you would prefer to write Python,
and can afford to write Python, we recommend using the Python interface to
PyTorch. However, if you would prefer to write C++, or need to write C++
(because of multithreading, latency or deployment requirements), the
C++ frontend to PyTorch provides an API that is approximately as convenient,
flexible, friendly and intuitive as its Python counterpart. The two frontends
serve different use cases, work hand in hand, and neither is meant to
unconditionally replace the other.

Installation
------------

Instructions on how to install the C++ frontend library distribution, including
an example for how to build a minimal application depending on LibTorch, may be
found by following `this <https://pytorch.org/cppdocs/installing.html>`_ link.