New src-layout and extensions framework

[dsvandet]

Summary

Update for:

1. Refactoring of project layout and build system (src-layout, CMake, Pybind11, setuptools)
2. Refactoring of extensions
3. Removal of unnecessary components
4. Pylint and Black Errors

This PR handles or partially handles the following Issues:

#312 [Full] - Main branch is not passing tests
#303 [Partial] - Installing fails: building editable results in error
#270: [Full] - File clean up

Details and comments

The current C++ analysis extensions are causing several issues: cyclic imports, not passing tests and compiling on Windows machines. In order to fix this problem these extensions where refactored and a new build system was implemented. This result is aimed at fixing these issues and creating a good framework for extensions (C, C++, Julia, Rust, etc).

The new structure switches from the ad-hoc-layout to the src-layout. The is useful for extensions and for reasons that can be read here (for example: https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/ or https://hynek.me/articles/testing-packaging/ etc.)

The new src-layout has the following structure:

qiskit_qec
├── CMakeLists.txt
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE.txt
├── MANIFEST.in
├── README.md
├── pyproject.toml
├── requirements-dev.txt
├── requirements.txt
├── setup.py
├── tox.ini
├── build_files/cmake
├── docs
├── extern
├── gap
├── intern
├── releasenotes
├── src
│   └── qiskit_qec
│            ├── __init__.py
│            ├── CMakeLists.txt
│            ├── VERSION.txt
│            ├── analysis
│            ├── circuits
│            └── ...
│   └── CMakeLists.txt
└── test
│     └── ...
├── tools
│   └── ...

The contents of the new directory structure are as follows:

The primary source code for the framework is contained within the src directory. The extern directory contains libraries needed by the framework that my not be on an individuals machine. The outer most intern directory contains libraries and code that are developed for the framework but that are not specific to QEC. The inner intern directories contain code for extensions is internal to the project and that are not needed to link to the extensions (e.g. cpp files, for internal header files). Public header files and such are stored in the primary category directories (such as analysis or operators). The bindings directories contain extension code to bind libraries to Python.

NOTE: pybind11 is currently included directly. This will make it easier for people but should belater removed in favor of find_package(PYBIND11 REQUIRED) or other methods.

Support Files

Directory/File	Use
/doc/	Documentation
/releasenotes	Release notes
/test	Files for testing

Build System

Directory/File	Use
/build_files/	Files needs when building the source
/build_files/cmake/	CMake build-system modules/macros
/CMakeLists.txt	CMake build file

Framework Code (/src/)

Directory/File	Use
/src/	Main source directory for framework code
/src/qiskit_qec	Primary python package source code
/src/qiskit_qec/analysis	Code for analysis capabilities and extension headers
/src/qiskit_qec/analysis/bindings	Binding code to bind analysis extensions to python
/src/qikit_qec/analysis/intern/	Internal source code for analysis extension
/src/qiskit_qec/circuits	Code for circuits capabilities and extension headers
/src/qiskit_qec/analysis	Code for analyzing codes
/src/qiskit_qec/codes	Code for the construction of codes
/src/qiskit_qec/exceptions.py	Module that imports the extensions and extension import flags
/src/qiskit_qec/info	Information module code
/src/qiskit_qec/noise	Code for noise models
/src/qiskit_qec/structures	Code for mathematical structures
/src/qiskit_qec/VERSION.txt	Primary version file
/src/qiskit_qec/circuits	Code for the construction of circuits
/src/qiskit_qec/decoders	Code for the decoders
/src/qiskit_qec/geometry	Code for geometry of codes
/src/qiskit_qec/linear	Code for linear algebra and algebra in general or codes
/src/qiskit_qec/operators	Code to Pauli and other types of operators
/src/qiskit_qec/utils	Code for utilities used by other modules

Internal Framework Code (/intern/)

Directory/File	Use
`/intern/	Internal source code that is used by the framework but is not QEC related

External Framework Code (/extern/)

Directory/File	Use
/extern/	External source code that is used by the framework but that is not expected to be on a users machine

Build System

The build system is based on the following components:

Library	Use
setuptools	Packaging for framework
setuptools_rust	Plugin to setuptools for Rust extensions
CMake	Build system for C/C++ and other language extensions
pybind11	Binding C/C++ to Python
Julia	Binding Julia to Python
Cargo	Building Rust libraries

Extensions

Code for extensions are split into libraries and python bindings. The library should be usable directly. The bindings simply bind python methods to the library methods. The bindings code is stored in one of the the bindings directories located in the appropriate category directory (e.g. analysis or operator or linear etc). Public header files should be in the main category directory. Internal header and base code should be in the intern directories that are located next with the bindings directories. The CMakeLists.txtfile for building the library should be in the primary category directory.

An example binding CMakeLists.txt file is as follows:

# Analysis library
cmake_minimum_required(VERSION 3.12)
project(Analysis)

set(ANALYSIS_SRC
    intern/combinations.cpp
    intern/distance.cpp
    intern/errorpropagator.cpp
    intern/faultenumerator.cpp
    intern/faultsampler.cpp
    intern/linear.cpp
    intern/productiterator.cpp
    
    combinations.h
    distance.h
    errorpropagator.h
    faultenumerator.h
    faultsampler.h
    linear.h
    productiterator.h
)

add_library(libanalysis
    STATIC
    ${ANALYSIS_SRC}
)

target_include_directories(libanalysis
    PUBLIC
    "${CMAKE_CURRENT_SOURCE_DIR}"
)

if (NOT (MSVC))
    target_compile_options(libanalysis PRIVATE -fno-strict-aliasing -fPIC ${ARCH_OPT})
else ()
    target_compile_options(libanalysis PRIVATE -fPIC ${ARCH_OPT})
endif ()

# Set prefix to "" since lib is already in project name
set_target_properties(libanalysis PROPERTIES PREFIX "")

Refactoring of the Analysis extension:

The analysis extension has been refactored. The primary module is qiskit_qec.analysis._c_analysis. The following C/C++ extensions are available:

Extension Method	Description	Flag
_CErrorPropagator	Error Propagator	C_ERROR_PROPAGATOR
_CFaultEnumerator	Fault Enumerator	C_FAULT_ENUMERATOR
_CFaultSampler	Fault Sampler	C_FAULT_SAMPLER
_c_minimum_distance	Minimum distance method	C_MIN_DISTANCE
_c_minimum_distance_by_tests	Minimum distance by tests method	C_MIN_DISTANCE_BY_TESTS
_c_rank	Rank	C_RANK
_c_isotropic	Is isotropic method	C_ISOTROPIC

The flag can be used to check if a given extension is available: For example:

from qiskit_qec.analysis.extensions import C_RANK

if C_RANK is True:
    from qiskit_qec.analysis.extensions import _c_rank

Some stuff  defining matrix
if C_RANK is True:
    return _c_rank(matrix)

Note: Do NOT load extensions directly into one the category dunder init files (__init__.py) as this will cause cyclic imports. If this is wanted than create a python wrapper, like minimum_distance that loads the extension from the appropriate extensions module, and import that wrapper instead.

The Python interface to these analysis extensions has slight changed:

1. The old ErrorProbagator class has been renamed BaseErrorProbagator
2. An error propagator is now created directly as follows: ep = ErrorProbagator() and this will return either the python only propagator or the C extension version. The EPSelector is no longer needed.

Building the Framework

The framework can be built with:

pip install .

or if editable mode is wanted:

pip install -e .