qupled 1.0.2__tar.gz → 1.1.0__tar.gz

qupled-1.1.0/.devcontainer/Dockerfile

@@ -0,0 +1,25 @@
+FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04
+
+# Install Python and clean up
+RUN apt-get update && apt-get install -y \
+    python3 python3-venv python3-pip && \
+    rm -rf /var/lib/apt/lists/*
+
+# Set up Python environment
+ENV PYTHON_VENV_ROOT=/workspaces/qupled_venv
+RUN python3 -m venv $PYTHON_VENV_ROOT && \
+    chown -R vscode:vscode $PYTHON_VENV_ROOT
+
+# Copy project files, set permissions, and install dependencies
+ENV SETUP_DIR=/setup_dir
+COPY dev $SETUP_DIR/dev/
+COPY devtool $SETUP_DIR/devtool
+WORKDIR $SETUP_DIR
+RUN chmod +x devtool && \
+    . $PYTHON_VENV_ROOT/bin/activate && \
+    ./devtool install-deps
+WORKDIR /
+RUN rm -rf $SETUP_DIR
+
+# Automatically activate the Python environment on container start
+RUN echo "source $PYTHON_VENV_ROOT/bin/activate" >> /etc/bash.bashrc

qupled-1.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,16 @@
+{
+  "name": "Development Container",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {},
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance"
+      ]
+    }
+  }
+}

{qupled-1.0.2 → qupled-1.1.0}/.gitignore

@@ -1,11 +1,13 @@
-*~
-*#
-Makefile
-docs/_build
 *.DS_Store
-*__pycache__
+*.db
 *.vscode
+*#
+*~
+*__pycache__
+.venv
 .tox
+Makefile
 dist
 dist-native-only
+docs/_build
 qupled.egg-info

{qupled-1.0.2 → qupled-1.1.0}/PKG-INFO

@@ -1,19 +1,19 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: qupled
-Version: 1.0.2
+Version: 1.1.0
 Summary: qupled: a package to investigate quantum plasmas via the dielectric formalism
 Author-email: Federico Lucco Castello <federico.luccocastello@gmail.com>
+License-Expression: GPL-3.0-or-later
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
-Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Requires-Python: <3.14,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: blosc2~=3.2
 Requires-Dist: matplotlib~=3.7
 Requires-Dist: numpy<2.0
-Requires-Dist: pandas~=2.0
-Requires-Dist: tables~=3.10
+Requires-Dist: SQLAlchemy~=2.0
 Provides-Extra: testing
 Requires-Dist: pytest~=8.0; extra == "testing"
 Requires-Dist: pytest-mock~=3.12; extra == "testing"
@@ -26,6 +26,7 @@ Requires-Dist: sphinxcontrib-jquery~=4.1; extra == "docs"
 Requires-Dist: sphinxcontrib-jsmath~=1.0.1; extra == "docs"
 Requires-Dist: sphinxcontrib-qthelp~=2.0.0; extra == "docs"
 Requires-Dist: sphinxcontrib-serializinghtml~=2.0.0; extra == "docs"
+Dynamic: license-file
 
 # Qupled
 
@@ -41,18 +42,18 @@ Qupled is a Python package designed for calculating the properties of quantum pl
  
 ## Running 
 
-After [installation](https://qupled.readthedocs.io/en/latest/introduction.html#installing-qupled) qupled can be used as a regular Python package
+After [installation](https://qupled.readthedocs.io/en/latest/introduction.html#installing-qupled) qupled can be used as a regular Python package.
 
 ```python
 # Solve the stls dielectric scheme for coupling = 10 and degeneracy 1.0
-from qupled.classic import Stls
-inputs = Stls.Input(10.0, 1.0)
-Stls().compute(inputs)
+import qupled.stls as stls
+inputs = stls.Input(10.0, 1.0)
+stls.Stls().compute(inputs)
 ```
 
 ## Documentation
 
-More detailed information on the package together with a list of examples is available in the [documentation](http://qupled.readthedocs.io/)
+More detailed information on the package together with a list of examples is available in the [documentation](http://qupled.readthedocs.io/).
 
 ## Publications
 

{qupled-1.0.2 → qupled-1.1.0}/README.md

@@ -12,18 +12,18 @@ Qupled is a Python package designed for calculating the properties of quantum pl
  
 ## Running 
 
-After [installation](https://qupled.readthedocs.io/en/latest/introduction.html#installing-qupled) qupled can be used as a regular Python package
+After [installation](https://qupled.readthedocs.io/en/latest/introduction.html#installing-qupled) qupled can be used as a regular Python package.
 
 ```python
 # Solve the stls dielectric scheme for coupling = 10 and degeneracy 1.0
-from qupled.classic import Stls
-inputs = Stls.Input(10.0, 1.0)
-Stls().compute(inputs)
+import qupled.stls as stls
+inputs = stls.Input(10.0, 1.0)
+stls.Stls().compute(inputs)
 ```
 
 ## Documentation
 
-More detailed information on the package together with a list of examples is available in the [documentation](http://qupled.readthedocs.io/)
+More detailed information on the package together with a list of examples is available in the [documentation](http://qupled.readthedocs.io/).
 
 ## Publications
 

{qupled-1.0.2 → qupled-1.1.0}/dev/devtool.py

@@ -5,9 +5,9 @@ import shutil
 from pathlib import Path
 
 
-def build(nompi, native_only):
+def build(no_mpi, native_only):
     # Build without MPI
-    if nompi:
+    if no_mpi:
         os.environ["USE_MPI"] = "OFF"
     # Set environment variable for OpenMP on macOS
     if os.name == "posix" and shutil.which("brew"):
@@ -46,8 +46,11 @@ def run_tox(environment):
         subprocess.run(["tox", "-e", environment], check=True)
 
 
-def test():
-    run_tox("test")
+def test(no_native):
+    if no_native:
+        run_tox("no_native")
+    else:
+        run_tox("test")
 
 
 def examples():
@@ -83,49 +86,39 @@ def clean():
 def install():
     wheel_file = get_wheel_file()
     if wheel_file is not None:
-        subprocess.run(["pip", "install", "--force-reinstall", wheel_file], check=True)
+        subprocess.run(["pip", "uninstall", "-y", wheel_file], check=True)
+        subprocess.run(["pip", "install", wheel_file], check=True)
 
 
 def install_dependencies():
     print("Installing dependencies...")
+    script_dir = Path(__file__).resolve().parent
+    pip_requirements = script_dir / "requirements-pip.txt"
     if os.name == "posix":
         if shutil.which("apt-get"):
-            subprocess.run(["sudo", "apt-get", "update"], check=True)
-            subprocess.run(
-                [
-                    "sudo",
-                    "apt-get",
-                    "install",
-                    "-y",
-                    "cmake",
-                    "libboost-all-dev",
-                    "libopenmpi-dev",
-                    "libgsl-dev",
-                    "libomp-dev",
-                    "libfmt-dev",
-                    "python3-dev",
-                ],
-                check=True,
-            )
+            _install_with_apt(script_dir / "requirements-apt.txt")
         elif shutil.which("brew"):
-            subprocess.run(["brew", "update"], check=True)
-            subprocess.run(
-                [
-                    "brew",
-                    "install",
-                    "cmake",
-                    "gsl",
-                    "libomp",
-                    "openmpi",
-                    "fmt",
-                    "boost-python3",
-                ],
-                check=True,
-            )
+            _install_with_brew(script_dir / "requirements-brew.txt")
         else:
             print("Unsupported package manager. Please install dependencies manually.")
     else:
         print("Unsupported operating system. Please install dependencies manually.")
+    subprocess.run(["pip", "install", "-r", str(pip_requirements)], check=True)
+
+
+def _install_with_apt(apt_requirements):
+    subprocess.run(["sudo", "apt-get", "update"], check=True)
+    with apt_requirements.open("r") as apt_file:
+        subprocess.run(
+            ["xargs", "sudo", "apt-get", "install", "-y"],
+            stdin=apt_file,
+            check=True,
+        )
+
+
+def _install_with_brew(brew_requirements):
+    subprocess.run(["brew", "update"], check=True)
+    subprocess.run(["brew", "bundle", f"--file={brew_requirements}"], check=True)
 
 
 def update_version(build_version):
@@ -154,7 +147,7 @@ def run():
     # Build command
     build_parser = subparsers.add_parser("build", help="Build the qupled package")
     build_parser.add_argument(
-        "--nompi",
+        "--no_mpi",
         action="store_true",
         help="Build without MPI support (default: False).",
     )
@@ -164,6 +157,14 @@ def run():
         help="Build only native code in C++ (default: False).",
     )
 
+    # Test command
+    test_parser = subparsers.add_parser("test", help="Run tests")
+    test_parser.add_argument(
+        "--no-native",
+        action="store_true",
+        help="Exclude the tests for the native classes (default: False).",
+    )
+
     # Update version command
     version_parser = subparsers.add_parser(
         "update-version", help="Update package version"
@@ -177,12 +178,11 @@ def run():
     subparsers.add_parser("format", help="Format the source code")
     subparsers.add_parser("install", help="Install the qupled package")
     subparsers.add_parser("install-deps", help="Install system dependencies")
-    subparsers.add_parser("test", help="Run tests")
 
     args = parser.parse_args()
 
     if args.command == "build":
-        build(args.nompi, args.native_only)
+        build(args.no_mpi, args.native_only)
     elif args.command == "clean":
         clean()
     elif args.command == "docs":
@@ -194,7 +194,7 @@ def run():
     elif args.command == "install":
         install()
     elif args.command == "test":
-        test()
+        test(args.no_native)
     elif args.command == "install-deps":
         install_dependencies()
     elif args.command == "update-version":

qupled-1.1.0/dev/requirements-apt.txt

@@ -0,0 +1,10 @@
+clang-format
+cmake
+libboost-all-dev
+libopenmpi-dev
+libgsl-dev
+libomp-dev
+libfmt-dev
+python3-dev
+libsqlite3-dev
+libsqlitecpp-dev

qupled-1.1.0/dev/requirements-brew.txt

@@ -0,0 +1,9 @@
+brew "clang-format"
+brew "cmake"
+brew "gsl"
+brew "libomp"
+brew "open-mpi"
+brew "fmt"
+brew "boost-python3"
+brew "sqlite"
+brew "sqlitecpp"

{qupled-1.0.2 → qupled-1.1.0}/docs/conf.py

@@ -23,7 +23,7 @@ extensions = ["sphinx.ext.napoleon", "sphinx.ext.autodoc", "sphinx.ext.mathjax"]
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 autodoc_member_order = "bysource"
-autodoc_mock_imports = ["qupled.native"]
+autodoc_mock_imports = ["qupled.native", "sqlalchemy", "blosc2"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

qupled-1.1.0/docs/contribute.rst

@@ -0,0 +1,61 @@
+How to contribute
+=================
+
+The following guidelines explain how to contribute to both the codebase and the documentation. 
+
+Setup the development environment
+---------------------------------
+
+There are two options for setting up your development environment:
+
+1. **The Easy Option: Use the Development Container**
+
+   This project includes a pre-configured development container to simplify the setup process. 
+   The development container provides all necessary tools, including an up-to-date version of Git, 
+   Python, and other dependencies.
+
+   To use the development container, ensure you have Docker and Visual Studio Code installed. 
+   Then, open the project in Visual Studio Code and follow these steps:
+
+   - Install the `Remote - Containers` extension if you haven't already.
+   - When prompted, reopen the project in the container.
+
+   Once the container is running, all tools and dependencies will be available in the environment. 
+   You can start developing immediately without additional setup.
+
+2. **The DIY Option: Manual Setup**
+
+   If you prefer to set up the environment manually, start by installing the required Python 
+   packages with the following command:
+
+   .. code-block:: console
+
+      pip install -r dev/requirements.txt
+
+   Additionally, ensure that you have all the necessary :ref:`external dependencies <external_dependencies>` 
+   installed.
+
+Formatting
+----------
+
+To maintain consistent code formatting across the C++ and Python codebases, we use
+`clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_ and
+`black <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_.
+The formatting is automatically checked every time new code is pushed to the repository.
+To manually ensure the correct formatting is applied, run:
+
+.. code-block:: console
+
+   ./devtool format
+
+Documentation
+-------------
+
+The documentation is stored in the ``docs`` directory, and changes can be made by editing the ``.rst`` files within it.
+Once you've made your changes, you can verify and build the documentation using:
+
+.. code-block:: console
+
+   ./devtool docs
+
+The generated output can be viewed by opening ``docs/_build/index.html`` in your browser.

qupled-1.1.0/docs/examples.rst

@@ -0,0 +1,110 @@
+Examples
+========
+
+The following examples present some common use cases that show how to run qupled and how to post-process the results.
+
+Setup a scheme and analyze the output
+-------------------------------------
+
+This example sets up all the necessary objects to solve the RPA and ESA schemes and
+shows how to access the information stored in the output files produced at the
+end of the calculations
+
+.. literalinclude:: ../examples/docs/solve_rpa_and_esa.py
+   :language: python
+
+A simple STLS solution
+----------------------
+
+This example sets up a simple STLS calculation and  plots some of the results 
+that are produced once the calculation are completed. There are two ways to access
+the results of the calculation: Directly from the object used to perform the calculation
+or from the output file created at the end of the run. The example illustrates how
+the static structure factor can be accessed with both these methods. Other quantities
+can be accessed in the same way.
+
+.. literalinclude:: ../examples/docs/solve_stls.py
+   :language: python
+
+Solving the classical IET schemes
+----------------------------------
+
+This example shows how to solve two classical STLS-IET schemes: the STLS-HNC and
+the STLS-LCT schemes. The schemes are solved one after the other by simply
+updating the properties of the solution object.
+
+.. literalinclude:: ../examples/docs/solve_stls_iet.py
+   :language: python
+
+.. _solvingQuantumSchemes:
+
+Solving the quantum schemes
+---------------------------
+
+This example shows how to solve the quantum dielectric schemes QSTLS and QSTLS-LCT. 
+Since these schemes can have a relatively high computational cost, in this example 
+we limit the number of matsubara frequencies to 16, we use 16 OMP threads to 
+speed up the calculation and we employ a segregated approach to solve the two-dimensional 
+integrals that appear in the schemes. 
+
+.. literalinclude:: ../examples/docs/solve_quantum_schemes.py
+   :language: python
+
+Solving the VS schemes
+----------------------
+
+This example shows how to solve the classical VS-STLS scheme at finite temperature.
+First the scheme is solved up to rs = 2, then the results are
+plotted and then the calculation is resumed up to rs = 5. In the second
+part of the calculation, the pre-computed value of the free energy integrand
+available from the VS-STLS solution at rs = 2 is used in order to speed
+up the calculation.
+
+.. literalinclude:: ../examples/docs/solve_vsstls.py
+   :language: python
+
+This example shows how to solve the quantum version of the VS-STLS scheme.
+Following the same logic of the previous example we first solve the scheme
+up to rs = 1.0 and then we resume the calculation up to rs = 2.0 while using
+the pre-compute values of the free energy integrand.
+
+.. literalinclude:: ../examples/docs/solve_qvsstls.py
+   :language: python
+         
+Define an initial guess
+-----------------------
+
+The following example shows how to define an initial guess for the STLS scheme. If 
+an initial guess is not specified the code will use the default, namely zero static 
+local field correction.
+
+.. literalinclude:: ../examples/docs/initial_guess_stls.py
+   :language: python
+
+For other schemes the initial guess can be specified in a similar manner.
+         
+Speed-up the quantum schemes
+----------------------------
+
+The quantum schemes can have a significant computational cost. There are two strategies
+that can be employed to speed up the calculations:
+
+* *Parallelization*: qupled supports both multithreaded calculations with OpenMP and
+  multiprocessors computations with MPI. The number of OpenMP threads
+  can be specified in input (as shown in :ref:`this example<solvingQuantumSchemes>`).
+  Multiprocessor computations can be performed by running qupled as an MPI application:
+  ``mpirun -n <number_of_cores> python3 <script_using_qupled>``. OpenMP and MPI can be
+  used concurrently by setting both the number of threads and the number of cores.
+ 
+* *Pre-computation*: The calculations for the quantum schemes can be made significantly
+  faster if part of the calculation of the auxiliary density response can be skipped.
+  Qupled will look into the database used to store the results to try to find the 
+  necessary data to skip the full calculation of the auxiliary density response.
+
+The following example shows the effect of pre-computation. The example first
+computes the auxiliary density response for a given set of parameters and then
+it uses the pre-computed data to speed up the calculation of the auxiliary density
+response for a different set of parameters.
+
+.. literalinclude:: ../examples/docs/fixed_adr.py
+   :language: python

{qupled-1.0.2 → qupled-1.1.0}/docs/introduction.rst

@@ -37,14 +37,17 @@ is the Fermi energy and :math:`h` is Planck's constant.
 Installing qupled
 -----------------
 
+.. _external_dependencies:
+
 External dependencies
 ~~~~~~~~~~~~~~~~~~~~~
 
 The installation of qupled may require compiling some C++ code, depending on the platform and installation method.
 Therefore, ensure the following dependencies are met before attempting to install or run qupled:
 
-  - `CMake <https://cmake.org/download/>`_
   - `Boost <https://www.boost.org/doc/libs/1_80_0/libs/python/doc/html/index.html>`_
+  - `CMake <https://cmake.org/download/>`_
+  - `fmt <https://github.com/fmtlib/fmt>`_
   - `GNU Scientific Library <https://www.gnu.org/software/gsl/>`_
   - `OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_
   - `Open-MPI <https://www.open-mpi.org/software/ompi/v5.0/>`_
@@ -53,13 +56,13 @@ For linux distributions all these dependencies can be installed with
 
 .. code-block:: console
 
-   sudo apt-get install -y cmake libboost-all-dev libopenmpi-dev libgsl-dev libomp-dev libfmt-dev python3-dev
+   sudo apt-get install -y cmake libboost-all-dev libopenmpi-dev libgsl-dev libomp-dev libfmt-dev python3-dev libsqlite3-dev libsqlitecpp-dev
 
 For macOS they can be installed directly from homebrew
 
 .. code-block:: console
 
-   brew install cmake gsl libomp openmpi fmt boost-python3
+   brew install cmake gsl libomp openmpi fmt boost-python3 sqlite sqlitecpp
 
 Install with pip
 ~~~~~~~~~~~~~~~~