From 35e01d98abff5727de59484cb154a3a7e378c4c1 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Tue, 4 Feb 2025 07:38:49 -0800 Subject: [PATCH] Minor enhancements to README file & fix to setup.py (#934) * Minor enhancements to README file This fixes a couple of typos, adds a couple of badges, and tries to adjust some spacing issues. (The result looks better on PyPI than on GitHub because of GitHub's poor support for reStructuredText.) * Fix truncation of readme file contents The original code ended up cutting off the first line of the readme.rst file. Replaced it with something that doesn't do that and is a bit simpler. --- README.rst | 94 +++++++++++++++++++++++++++++++++--------------------- setup.py | 9 +++--- 2 files changed, 61 insertions(+), 42 deletions(-) diff --git a/README.rst b/README.rst index 6e55d45cc..8337ee709 100644 --- a/README.rst +++ b/README.rst @@ -1,40 +1,61 @@ -.. image:: docs/images/logo_horizontal.svg +.. image:: https://raw.githubusercontent.com/quantumlib/OpenFermion/refs/heads/master/docs/images/logo_horizontal.svg + :alt: OpenFermion logo + :width: 75% + :align: center -OpenFermion is an open source library for compiling and analyzing quantum -algorithms to simulate fermionic systems, including quantum chemistry. Among -other functionalities, this version features data structures and tools -for obtaining and manipulating representations of fermionic and qubit -Hamiltonians. For more information, see our -`release paper `__. +.. |ci| image:: https://img.shields.io/github/actions/workflow/status/quantumlib/openfermion/ci.yml?style=flat-square&logo=GitHub&label=Continous%20integration + :alt: Continuous integration status badge + :target: https://github.com/quantumlib/OpenFermion/workflows/Continuous%20Integration/badge.svg + +.. |python| image:: https://img.shields.io/badge/Python-3.10+-fcbc2c.svg?style=flat-square&logo=python&logoColor=white + :alt: Compatible with Python versions 3.10 and higher + :target: https://www.python.org/downloads/ +.. |license| image:: https://img.shields.io/badge/License-Apache%202.0-3c60b1.svg?logo=opensourceinitiative&logoColor=white&style=flat-square + :alt: Licensed under the Apache 2.0 license + :target: https://github.com/quantumlib/OpenFermion/blob/main/LICENSE +.. |version| image:: https://img.shields.io/pypi/v/OpenFermion.svg?logo=semantic-release&logoColor=white&label=Release&style=flat-square&color=fcbc2c + :alt: OpenFermion project on PyPI + :target: https://pypi.org/project/OpenFermion -.. image:: https://github.com/quantumlib/OpenFermion/workflows/Continuous%20Integration/badge.svg - :target: https://github.com/quantumlib/OpenFermion/workflows/Continuous%20Integration/badge.svg +.. |downloads| image:: https://img.shields.io/pypi/dm/openfermion?logo=PyPI&logoColor=white&style=flat-square&label=Downloads + :alt: OpenFermion downloads per month from PyPI + :target: https://img.shields.io/pypi/dm/OpenFermion -.. image:: https://readthedocs.org/projects/openfermion/badge/?version=latest - :target: http://openfermion.readthedocs.io/en/latest/?badge=latest - :alt: Documentation Status +.. class:: margin-top +.. class:: centered -.. image:: https://badge.fury.io/py/openfermion.svg - :target: https://badge.fury.io/py/openfermion +| +| |ci| |python| |license| |version| |downloads| -.. image:: https://img.shields.io/pypi/dm/openfermion - :target: https://img.shields.io/pypi/dm/openfermion +.. |vertspace| image:: https://upload.wikimedia.org/wikipedia/commons/archive/c/ca/20200404084254%211x1.png + :alt: Blank space + :width: 1px + :height: 30px +|vertspace| OpenFermion is an open source library for compiling and analyzing quantum +algorithms to simulate fermionic systems, including quantum chemistry. Among +other functionalities, it features data structures and tools for obtaining and +manipulating representations of fermionic and qubit Hamiltonians. For more +information, see our `release paper `__. -Run the interactive Jupyter Notebooks in Colab_ or MyBinder_: +You can run the interactive Jupyter Notebooks in |Colab|_ or |MyBinder|_. +.. |Colab| replace:: Colab .. _Colab: https://colab.research.google.com/github/quantumlib/OpenFermion -.. _MyBinder: https://mybinder.org/v2/gh/quantumlib/OpenFermion/master?filepath=examples +.. |MyBinder| replace:: MyBinder +.. _MyBinder: https://mybinder.org/v2/gh/quantumlib/OpenFermion/master?filepath=examples Installation and Documentation ============================== -Installing the latest **stable** OpenFermion requires pip. Make sure that you are using an up-to-date version of it. +Installing the latest **stable** OpenFermion requires the Python package +installer `pip `__. Make sure that you are using an +up-to-date version of it. -Documentation can be found at `quantumai.google/openfermion `__ and the following links +Documentation can be found at `quantumai.google/openfermion `__ and the following links: * `Installation `__ @@ -51,17 +72,13 @@ and usage instructions in the The Docker image provides a virtual environment with OpenFermion and select plugins pre-installed. The Docker installation should run on any operating system. -You might also want to explore the alpha release of the -`OpenFermion Cloud Library `__ -where users can share and download precomputed molecular benchmark files. - - Developer install ----------------- -To install the latest version of OpenFermion (in development mode): +To install the latest version of OpenFermion (in development mode), run +the following commands: -.. code-block:: bash +.. code-block:: shell git clone https://github.com/quantumlib/OpenFermion cd OpenFermion @@ -70,9 +87,10 @@ To install the latest version of OpenFermion (in development mode): Library install --------------- -To install the latest PyPI release as a library (in user mode): +To install the latest PyPI release as a library (in user mode), run +the following commands: -.. code-block:: bash +.. code-block:: shell python -m pip install --user openfermion @@ -84,21 +102,24 @@ Specifically, plugins are used to simulate and compile quantum circuits and to p classical electronic structure calculations. Follow the links below to learn more! -High performance simulators ------------------------------------------- +High-performance simulators +--------------------------- + * `OpenFermion-FQE `__ is - a high performance emulator of fermionic quantum evolutions specified + a high-performance emulator of fermionic quantum evolutions specified by a sequence of fermion operators, which can exploit fermionic symmetries such as spin and particle number. Circuit compilation plugins ------------------------------------------- +--------------------------- + * `Forest-OpenFermion `__ to support integration with `Forest `__. * `SFOpenBoson `__ to support integration with `Strawberry Fields `__. Electronic structure package plugins ------------------------------------ + * `OpenFermion-Psi4 `__ to support integration with `Psi4 `__. * `OpenFermion-PySCF `__ to support integration with `PySCF `__. @@ -112,8 +133,9 @@ How to contribute We'd love to accept your contributions and patches to OpenFermion. There are a few small guidelines you need to follow. -Contributions to OpenFermion must be accompanied by a Contributor License Agreement. -You (or your employer) retain the copyright to your contribution, +Contributions to OpenFermion must be accompanied by a Contributor License +Agreement (CLA). +You (or your employer) retain the copyright to your contribution; the CLA this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one. @@ -181,8 +203,6 @@ Authors `Fang Zhang `__ (University of Michigan) and `Emiel Koridon `__ (Leiden University). - - How to cite =========== When using OpenFermion for research projects, please cite: diff --git a/setup.py b/setup.py index f4015f4b6..362ef441b 100755 --- a/setup.py +++ b/setup.py @@ -9,7 +9,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -import io + import os from setuptools import find_packages, setup @@ -19,10 +19,9 @@ exec(open('src/openfermion/_version.py').read()) # Readme file as long_description: -long_description = '===========\n' + 'OpenFermion\n' + '===========\n' -stream = io.open('README.rst', encoding='utf-8') -stream.readline() -long_description += stream.read() +long_description = '===========\n' + 'OpenFermion\n' + '===========\n\n' +with open('README.rst', 'r', encoding='utf-8') as readme: + long_description += readme.read() # Read in package requirements.txt requirements = open('dev_tools/requirements/deps/runtime.txt').readlines()