larq / docs Goto Github PK

Docs website for Larq, Larq Zoo, and Larq Compute Engine

License: Apache License 2.0

Shell 2.08% Python 54.87% HTML 43.05%

docs's Introduction

Larq is an open-source deep learning library for training neural networks with extremely low precision weights and activations, such as Binarized Neural Networks (BNNs).

Existing deep neural networks use 32 bits, 16 bits or 8 bits to encode each weight and activation, making them large, slow and power-hungry. This prohibits many applications in resource-constrained environments. Larq is the first step towards solving this. It is designed to provide an easy to use, composable way to train BNNs (1 bit) and other types of Quantized Neural Networks (QNNs) and is based on the tf.keras interface. Note that efficient inference using a trained BNN requires the use of an optimized inference engine; we provide these for several platforms in Larq Compute Engine.

Larq is part of a family of libraries for BNN development; you can also check out Larq Zoo for pretrained models and Larq Compute Engine for deployment on mobile and edge devices.

Getting Started

To build a QNN, Larq introduces the concept of quantized layers and quantizers. A quantizer defines the way of transforming a full precision input to a quantized output and the pseudo-gradient method used for the backwards pass. Each quantized layer requires an input_quantizer and a kernel_quantizer that describe the way of quantizing the incoming activations and weights of the layer respectively. If both input_quantizer and kernel_quantizer are None the layer is equivalent to a full precision layer.

You can define a simple binarized fully-connected Keras model using the Straight-Through Estimator the following way:

model = tf.keras.models.Sequential(
    [
        tf.keras.layers.Flatten(),
        larq.layers.QuantDense(
            512, kernel_quantizer="ste_sign", kernel_constraint="weight_clip"
        ),
        larq.layers.QuantDense(
            10,
            input_quantizer="ste_sign",
            kernel_quantizer="ste_sign",
            kernel_constraint="weight_clip",
            activation="softmax",
        ),
    ]
)

This layer can be used inside a Keras model or with a custom training loop.

Examples

Check out our examples on how to train a Binarized Neural Network in just a few lines of code:

Installation

Before installing Larq, please install:

Python version 3.7, 3.8, 3.9, or 3.10
Tensorflow version 1.14, 1.15, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, or 2.10:
```
pip install tensorflow  # or tensorflow-gpu
```

You can install Larq with Python's pip package manager:

pip install larq

About

Larq is being developed by a team of deep learning researchers and engineers at Plumerai to help accelerate both our own research and the general adoption of Binarized Neural Networks.

docs's People

Contributors

Stargazers

Watchers

Forkers

lfolkerts akifavcu

docs's Issues

Number alignment in columns

As mentioned in comments of #149, tables would be more readable if numbers were aligned using all the known best practices. In practice, this would mean using a fixed-width font for numbers in tables and right-aligning columns with numbers (assuming they all have the same number of decimal places).

Docs browser compatability issue: logo reloading

I know browser compatability is boring, but on Firefox the logo gets removed and re-loaded on each click of the top nav, as demonstrated by this screen recording (the GIF converter I used dropped several frames so it looks like the reloading didn't happen for the middle item, but it did).

This actually isn't just the top nav, it happens when clicking on anything in the left-hand nav bar too.

Works as expected on Chromium.

Originally posted by @AdamHillier in larq/larq#418 (comment)

This was a comment on the PR linked above, so the recording is of a preview of the new docs site, but the issue also arises with the existing site.

[LCE] Add End-to-End example

It would be great to have an end-to-end example walking user through the entrie process of building a model with larq and converting and deploying it with LCE

Bring back "papers using larq"

Papers using larq should be added to FAQ again, currently it is not linked in the website

Reformat markdown files to be one-sentence-per-line

This makes it easier to read diffs.

Switch from binder to colab

We currently allow users to run notebooks on Binder. Unfortunately the Docker build takes quite some time which is discouraging.

I think we should switch to https://colab.research.google.com/ which has support for GPUs or we invest time in pre-building a Docker container to speedup Binder.

We should also integrate some of the content in https://tiny.cc/ucl-bnn

Implement auto-dark mode

Partially enabled by #111, but we should wait until we can follow the user's OS-level preference (defaulting to light if none is set); see squidfunk/mkdocs-material#1266.

Mismatch between zoo model stats and model summary

The stats reported for Larq Zoo models in the table here are very slightly different the stats reported in the model summary. Specifically, the number of parameters is slightly wrong (off by a few hundred).

I think this is probably because of larq/larq#454.

Fix notebook anchorlinks

Anchor links don't render properly: https://docs.larq.dev/larq/tutorials/mnist/

More info greenape/mknotebooks#16

`BinaryAlexNet function` instead of `BinaryAlexNet`

The zoo API pages (literature, sota) append the headings with "function". Apart from not being very pretty, this has broken all the links in tables like the ones here. @leonoverweel do you know why the "function" has been added, and can it be removed?

Add guide for exporting binarized weights

This is much easier now with the quantized variable scope in larq>=0.9, and it's a question that gets asked a lot (e.g. larq/larq#360 and larq/larq#406). We should add a guide + code snippet explaining how to do this somewhere in the docs.

[LCE] Add "Optimizing models for LCE" guide

We should have a guide that describes best practices and current limitations of LCE

Improve CSS of rendered notebooks

The rendering of https://docs.larq.dev/larq/tutorials/mnist/ needs some small updates to fit with the rest of the site.

Depends on greenape/mknotebooks#28

Mention larq/zoo more clearly on the frontpage and readme

larq/zoo is an important part of larq, so we should mention it prominently on the Readme and the front page. Otherwise it can be hard for new users to discover.

Broken menu on chrome for android

When going into the third menu down on docs.larq.dev using chrome on my phone (Pixel 2) the menu is broken. Specifically, text from higher level menus is shown as well as (and through) the text of that level. This does not happen with firefox on my phone or chrome on desktop.

Below is a screenshot from going to top level > Compute Engine > Build, with chrome left and firefox right:

Similar things happen when going into other sub-menus at this level (e.g. Larq -> User Guides).

Hyperparameter heading not rendered

The heading for HyperparameterScheduler is not rendered, as shown in the screenshot. (Separately, argument ordering is off here but this is solved in larq/larq#455.)

[LCE] Benchmarking guide

Add guide that walks user through the process of converting and benchmarking a Larq model on an android phone or raspberry pi.

Minor layout bug with docs headers

When the header length is just under the width of the md-content <div>, there is incorrectly a double line break before the content. This can be seen below (the "Can I use Larq only ..." block):

The issue arises because of the "anchor" button, which is invisible unless you hover over it. When hovering, the header looks like this:

When not hovering over it, it overflows onto the next line but is invisible so it looks like an (additional) line break before the content.

Add section about performance claims of quantized/binarized NNs

In openjournals/joss-reviews#1746 @sbrugman raised a very valid point that is currently missing in our guides and documentation:

The documentation and paper make no claims on the comparison of performance between Quantized Neural Networks and their high-precision weight and bias counterparts. At the time of writing, there is clearly a trade-off (although the authors are working hard to close the gap). I suggest being transparent in this difference and possibly opening the option of educating users on when a few percents of accuracy on a specific dataset are essential and when not. This might be especially relevant for people working in the industry.

I think it would be good to add a small paragraph to our FAQ or the guides that briefly explains the story about efficiency and the challenges and of quantized networks as well as what theoretical speedups someone can expect. In general this always depends on the choice of networks and hardware used to run the models, but I agree that we should be transparent about this.

@jamescook106 @koenhelwegen Do we have some resources we could use to elaborate on our claims on the home page?