Contributing templates

The following steps will help you to add your favourite circuit ansatz to PennyLane’s template library.

PennyLane internally distinguishes different types of templates, such as embeddings, layers, state_preparations or subroutines. Here we will use the template MyNewTemplate as an example, and you need to replace <templ_type> with the correct template type.

Adding the template

Add the template by adding a new file my_new_template.py to the correct templates/<templ_type>/ subdirectory. The file contains your new template, which is a function that defines a sequence of quantum gates (without measurements).

For example, this is a very basic template applying an RX gate to each wire:

import pennylane as qml
from pennylane.templates import template  # import the decorator

@template
def MyNewTemplate(weights, wires):

    # Check that the inputs have the correct format
    # ...

    for wire, weight in zip(wires, weights):
        qml.RX(weight, wires=wire)

Since the template is called within a quantum function, it can only contain information processing that is allowed inside a quantum functions.

Make sure you consider the following:

• Choose the name carefully. Good names tell the user what a template is good for, or what architecture it implements. To be consistent with other quantum operations (which are classes), the function name (i.e., MyNewTemplate) is written in camel case.

• Register the template. A template is “registered” by using the template decorator @template. This allows us to record the queue of operations of a template, which is very useful for testing:

  with qml.utils.OperationRecorder() as rec:
      MyNewTemplate(...)
  
  list_of_gates = rec.queue
  

• Consider using the broadcast() function to make your code more concise.

• Write an extensive docstring that explains how to use the template. Include a sketch of the template (add the file to the doc/_static/templates/<templ_type>/ directory). You can also display a small usage example at the beginning of the docstring.

  At the end of the docstring, add a section starting with the .. UsageDetails:: directive, where you demonstrate with code examples how to use the templates with different settings, for example varying the number of wires, explaining keyword arguments and special cases. Use the docstring of one of the existing templates for inspiration, such as AmplitudeEmbedding.

• Check the inputs to the template. You can use the functions provided in utils. Don’t forget that arguments may be passed by the user to the qnode as primary or auxiliary quantum function arguments, and by using different interfaces (i.e., an input could be a numpy.ndarray or a list of Variable, depending on how the user uses the template).

Importing the new template

Import the new template in templates/<templ_type>/__init__.py by adding the new line

from .mynewtemplate import MyNewTemplate

Adding your template to the documentation

Add your template to the documentation by adding a customgalleryitem to the correct layer type section in doc/introduction/templates.rst:

.. customgalleryitem::
  :link: ../code/api/pennylane.templates.<templ_type>.MyNewTemplate.html
  :description: MyNewTemplate
  :figure: ../_static/templates/<templ_type>/my_new_template.png

Note

This loads the image of the template added to doc/_static/templates/<templ_type>/ in Step 1. Make sure that this image has the same dimensions and style as other template icons in the folder.

Adding tests

Add tests for your new template to the test suite.

• Integration tests, which check that your template can be called inside a quantum node and that PennyLane can compute gradients with respect to differentiable parameters, are added to tests/test_templates.py. Simply add your template to the fixtures as explained in the docstring.

• Add a new test class to tests/test_templates_<templ_type>.py that contains the unit tests for the template. Make sure you test all keyword arguments and edge cases like using a single wire.