Mr Mustard requires the following libraries be installed:
Python >= 3.9
as well as the following Python packages:
If you currently do not have Python 3 installed, we recommend Anaconda for Python 3, a distributed version of Python packaged for scientific computation.
For development purposes, it is recommended to install the Mr Mustard source code using development mode:
git clone https://github.com/XanaduAI/MrMustard
pip install -e .
-e flag ensures that edits to the source code will be reflected when
importing Mr Mustard in Python.
Increased numerical stability using Julia [optional]¶
Converting phase space objects to Fock space can be numerically unstable due to accumulating floating point errors. To resolve this, the conversion can be performed with extended-precision arithmetic. To use this feature, an installation of Julia is required (version 1.9.3 recommended).
When installing MrMustard via devcontainer, Julia and its required packages are automatically installed.
When installing MrMustard via
pip install, the required Julia packages have to be installed manually as follows:
julia --project="julia_pkg" -e "using Pkg; Pkg.instantiate()"
When installing MrMustard via the MakeFile, the required Julia packages are automatically installed only if Julia was previously installed by the user.
Mr Mustard uses a
pytest suite for testing and
black for formatting. These
dependencies can be installed via
poetry install --with dev
To ensure that Mr Mustard is working correctly after installation, the test suite can be run by navigating to the source code folder and running
Individual test modules are run by invoking pytest directly from the command line:
--backend flag allows specifying the backend used when running the tests. To
use the numpy backend, type
pytest tests/test_fidelity.py or
pytest tests/test_fidelity.py --backend=numpy.
To use the tensorflow backend, run the command
pytest tests/test_fidelity.py --backend=tensorflow.
Run options for Mr Mustard tests
When running tests, it can be useful to examine a single failing test. The following command stops at the first failing test:
For further useful options (e.g.
refer to the
pytest --help command line usage description or the
pytest online documentation.
Test coverage can be checked by running
The output of the above command will show the coverage percentage of each file, as well as the line numbers of any lines missing test coverage.
To obtain coverage, the
pytest-cov plugin is needed.
The coverage of a specific file can also be checked by generating a report:
pytest tests/test_fidelity.py --cov=mrmustard/location/to/module --cov-report=term-missing
Here the coverage report will be created relative to the module specified by
the path passed to the
The previously mentioned
pytest options can be combined with the coverage
options. As an example, the
-k option allows you to pass a boolean string
using file names, test class/test function names, and marks. Using
the following command we can get the report of a specific file while also
filtering out certain tests:
pytest tests/test_fidelity.py --cov --cov-report=term-missing -k 'not test_fidelity_coherent_state'
--cov option without any modules specified will generate a
coverage report for all modules of Mr Mustard.
Format and code style¶
Contributions are checked for format alignment in the pipeline. With
installed, changes can be formatted locally using:
make installed can run
black directly using:
black -l 100 mrmustard
Contributions are checked for format alignment in the pipeline. Changes can be formatted and linted locally using:
To run both linting and formatting use
make format lint
Additional packages are required to build the documentation, as specified in
pyproject.toml under the group
doc. These packages can be installed using:
poetry install --with doc
from within the top-level directory. To then build the HTML documentation, run
The documentation can be found in the
Submitting a pull request¶
Before submitting a pull request, please make sure the following is done:
All new features must include a unit test. If you’ve fixed a bug or added code that should be tested, add a test to the
All new functions and code must be clearly commented and documented.
Have a look through the source code at some of the existing function docstrings— the easiest approach is to simply copy an existing docstring and modify it as appropriate.
If you do make documentation changes, make sure that the docs build and render correctly by running
Ensure that the test suite passes, by running
Make sure the modified code in the pull request conforms to the PEP8 coding standard.
black -l 100 mrmustard/path/to/modified/file.py
We check all of our code against Pylint for errors. To lint modified files, simply
pip install pylint, and then from the source code directory, run
When ready, submit your fork as a pull request to the Mr Mustard repository, filling out the pull request template. This template is added automatically to the comment box when you create a new issue.
When describing the pull request, please include as much detail as possible regarding the changes made/new features added/performance improvements. If including any bug fixes, mention the issue numbers associated with the bugs.
Once you have submitted the pull request, three things will automatically occur:
The test suite will automatically run on GitHub Actions to ensure that all tests continue to pass.
Once the test suite is finished, a code coverage report will be generated on Codecov. This will calculate the percentage of Mr Mustard covered by the test suite, to ensure that all new code additions are adequately tested.
Finally, the code quality is calculated by Codefactor, to ensure all new code additions adhere to our code quality standards.
Based on these reports, we may ask you to make small changes to your branch before merging the pull request into the master branch. Alternatively, you can also grant us permission to make changes to your pull request branch.