spinguin 0.0.1__tar.gz

spinguin-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Joni Eronen]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spinguin-0.0.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include src/spinguin/core/sparse_dot.pyx
+include src/spinguin/core/intersect_indices.pyx

spinguin-0.0.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: spinguin
+Version: 0.0.1
+Summary: Spinguin is an intuitive Python package for versatile numerical spin-dynamics simulations.
+Author-email: Joni Eronen <joni.eronen@oulu.fi>, Perttu Hilla <perttu.hilla@oulu.fi>
+License: MIT License
+        
+        Copyright (c) [2025] [Joni Eronen]
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy>=1.14.1
+Requires-Dist: sympy>=1.13.1
+Requires-Dist: joblib>=1.5.1
+Dynamic: license-file
+
+# Spinguin
+
+## Description
+Spinguin is a user-friendly Python package designed for versatile numerical
+spin-dynamics simulations in liquid state. It offers tools for performing
+simulations using restricted basis sets, enabling the use of large spin systems
+with more than 10 spins on consumer-level hardware. Spinguin supports the
+simulation of coherent dynamics, relaxation, and chemical exchange processes.
+
+## Documentation
+Documentation for the package is available here:
+https://nmroulu.github.io/Spinguin/
+
+## Installation
+Spinguin can be installed in various ways, depending on your needs and
+preferences. You can install it from the Python Package Index (PyPI) or build it
+from the source code available on GitHub. Below are the instructions for both
+methods.
+
+### Installation from PyPI
+Spinguin is available from the Python Package Index (PyPI) repository for
+Windows and Linux. To install the package, simply issue the command::
+
+```bash
+pip install spinguin
+```
+
+### Installation from source
+1. Ensure the `build` module is installed:
+    ```bash
+    pip install build
+    ```
+2. Download the source code archive (.zip or .tar.gz).
+3. Extract the archive (e.g., using 7-Zip).
+4. Navigate to the extracted folder:
+    ```bash
+    cd /your/path/spinguin-X.Y.Z
+    ```
+5. Build the wheel from the source:
+    ```bash
+    python -m build --wheel
+    ```
+6. Navigate to the `dist` folder:
+    ```bash
+    cd /your/path/spinguin-X.Y.Z/dist
+    ```
+7. Install the wheel using pip:
+    ```bash
+    pip install spinguin-X.Y.Z-cpXYZ-cpXYZ-PLATFORM.whl
+    ```
+
+## License
+This project is licensed under the [MIT License](LICENSE).

spinguin-0.0.1/README.md

@@ -0,0 +1,53 @@
+# Spinguin
+
+## Description
+Spinguin is a user-friendly Python package designed for versatile numerical
+spin-dynamics simulations in liquid state. It offers tools for performing
+simulations using restricted basis sets, enabling the use of large spin systems
+with more than 10 spins on consumer-level hardware. Spinguin supports the
+simulation of coherent dynamics, relaxation, and chemical exchange processes.
+
+## Documentation
+Documentation for the package is available here:
+https://nmroulu.github.io/Spinguin/
+
+## Installation
+Spinguin can be installed in various ways, depending on your needs and
+preferences. You can install it from the Python Package Index (PyPI) or build it
+from the source code available on GitHub. Below are the instructions for both
+methods.
+
+### Installation from PyPI
+Spinguin is available from the Python Package Index (PyPI) repository for
+Windows and Linux. To install the package, simply issue the command::
+
+```bash
+pip install spinguin
+```
+
+### Installation from source
+1. Ensure the `build` module is installed:
+    ```bash
+    pip install build
+    ```
+2. Download the source code archive (.zip or .tar.gz).
+3. Extract the archive (e.g., using 7-Zip).
+4. Navigate to the extracted folder:
+    ```bash
+    cd /your/path/spinguin-X.Y.Z
+    ```
+5. Build the wheel from the source:
+    ```bash
+    python -m build --wheel
+    ```
+6. Navigate to the `dist` folder:
+    ```bash
+    cd /your/path/spinguin-X.Y.Z/dist
+    ```
+7. Install the wheel using pip:
+    ```bash
+    pip install spinguin-X.Y.Z-cpXYZ-cpXYZ-PLATFORM.whl
+    ```
+
+## License
+This project is licensed under the [MIT License](LICENSE).

spinguin-0.0.1/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "spinguin"
+version = "0.0.1"
+dependencies = ["numpy >= 1.26.4", "scipy >= 1.14.1", "sympy >= 1.13.1", "joblib >= 1.5.1"]
+requires-python = ">=3.11"
+authors = [
+    {name = "Joni Eronen", email = "joni.eronen@oulu.fi"},
+    {name = "Perttu Hilla", email = "perttu.hilla@oulu.fi"}
+]
+description = "Spinguin is an intuitive Python package for versatile numerical spin-dynamics simulations."
+readme = "README.md"
+license = {file = "LICENSE"}
+
+[build-system]
+requires = ["setuptools>=74.1", "wheel", "cython >= 3.0.11", "numpy >= 1.26.4", "cibuildwheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.cibuildwheel]
+skip = ["*-win32"]

spinguin-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spinguin-0.0.1/setup.py

@@ -0,0 +1,39 @@
+"""
+This script is required for compiling the sparse_dot() and intersect_indices()
+Cython functions.
+"""
+
+from setuptools import Extension, setup
+from Cython.Build import cythonize
+import sys
+import numpy as np
+
+# Platform-specific compiler and linker settings
+if sys.platform == "win32":
+    extra_compile_args = ['/openmp', '/O2', '/arch:SSE2', '/GS-']
+    extra_link_args = []
+elif sys.platform == "linux":
+    extra_compile_args = ['-fopenmp', '-Ofast', '-march=native']
+    extra_link_args = ['-fopenmp']
+
+ext_modules = [
+    Extension(
+        name = "spinguin.core.sparse_dot",
+        sources = ["src/spinguin/core/sparse_dot.pyx"],
+        include_dirs = [np.get_include()],
+        extra_compile_args = extra_compile_args,
+        extra_link_args = extra_link_args,
+        language = 'c++'
+    ),
+    Extension(
+        name = "spinguin.core.intersect_indices",
+        sources = ["src/spinguin/core/intersect_indices.pyx"],
+        extra_compile_args = extra_compile_args,
+        extra_link_args = extra_link_args,
+        language = 'c++'
+    )
+]
+
+setup(
+    ext_modules=cythonize(ext_modules, annotate=True)
+)

spinguin-0.0.1/src/spinguin/__init__.py

@@ -0,0 +1,10 @@
+"""
+Spinguin package is desined to be imported as `import spinguin as sg`, which
+reveals the user-friendly functionality to the user. This is documented under
+the Spinguin (Basic). For more in-depth documentation of the package, including
+the documentation of the re-usable, core functionality, see Spinguin (Advanced).
+"""
+
+# Make functionality from the API accessible directly under the spinguin
+# namespace
+from spinguin.api import *

spinguin-0.0.1/src/spinguin/api/__init__.py

@@ -0,0 +1,41 @@
+"""
+This module provides user friendly wrapper functions of the Spinguin's core 
+functionality by making use of the `SpinSystem` class.
+"""
+
+# Expose only the necessary functions from the API
+from spinguin.api.core import (
+    alpha_state,
+    beta_state,
+    associate,
+    dissociate,
+    equilibrium_state,
+    frequency_to_chemical_shift,
+    hamiltonian,
+    inversion_recovery,
+    liouvillian,
+    measure,
+    operator,
+    permute_spins,
+    propagator,
+    propagator_to_rotframe,
+    pulse,
+    pulse_and_acquire,
+    relaxation,
+    resonance_frequency,
+    singlet_state,
+    spectral_width_to_dwell_time,
+    spectrum,
+    state,
+    state_to_zeeman,
+    superoperator,
+    time_axis,
+    triplet_minus_state,
+    triplet_plus_state,
+    triplet_zero_state,
+    unit_state
+)
+
+from spinguin.api.parameters import parameters
+
+from spinguin.api.spin_system import SpinSystem

spinguin-0.0.1/src/spinguin/api/basis.py

@@ -0,0 +1,161 @@
+"""
+This module provides the Basis class which is assigned as a part of `SpinSystem`
+object upon its instantiation. Here is an example of accessing the most
+important functionality of the class::
+
+    import spinguin as sg                   # Import the package
+    spin_system = sg.SpinSystem(["1H"])     # Create an example spin system
+    spin_system.basis.max_spin_order = 1    # Set the maximum spin order
+    spin_system.basis.build()               # Build the basis set
+"""
+
+# Referencing SpinSystem class
+from __future__ import annotations
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from spinguin.api.spin_system import SpinSystem
+
+# Imports
+import numpy as np
+import scipy.sparse as sp
+import warnings
+from spinguin.core.states import state_to_truncated_basis
+from spinguin.core.superoperators import sop_to_truncated_basis
+from spinguin.core.basis import make_basis, truncate_basis_by_coherence
+from spinguin.core.la import isvector
+
+class Basis:
+    """
+    Basis class manages the basis set of a spin system. Most importantly, the
+    basis set contains the information on the truncation of the basis set and is
+    responsible for building and making changes to the basis set.
+    """
+
+    # Basis set properties
+    _basis: np.ndarray = None
+    _max_spin_order: int = None
+    _spin_system: SpinSystem = None
+
+    def __init__(self, spin_system: SpinSystem):
+        print("Basis set has been initialized with the following defaults:")
+        print(f"max_spin_order: {self.max_spin_order}\n")
+
+        # Store a reference to the SpinSystem
+        self._spin_system = spin_system
+
+    @property
+    def dim(self) -> int:
+        """Dimension of the basis set."""
+        return self.basis.shape[0]
+
+    @property
+    def max_spin_order(self) -> int:
+        """
+        Specifies the maximum number of a active spins that are included in the
+        product operators that constitute the basis set. Must be at least 1 and
+        not larger than the number of spins in the system.
+        """
+        return self._max_spin_order
+    
+    @property
+    def basis(self) -> np.ndarray:
+        """
+        Contains the actual basis set as an array of dimensions (N, M) where
+        N is the number of states in the basis and M is the number of spins in
+        the system. The basis set is constructed from Kronecker products of
+        irreducible spherical tensor operators, which are indexed using integers
+        starting from 0 with increasing rank `l` and decreasing projection `q`:
+
+        - 0 --> T(0, 0)
+        - 1 --> T(1, 1)
+        - 2 --> T(1, 0)
+        - 3 --> T(1, -1) and so on...
+
+        """
+        return self._basis
+    
+    @max_spin_order.setter
+    def max_spin_order(self, max_spin_order):
+        if max_spin_order < 1:
+            raise ValueError("Maximum spin order must be at least 1.")
+        if max_spin_order > self._spin_system.nspins:
+            raise ValueError("Maximum spin order must not be larger than "
+                             "the number of spins in the system.")
+        self._max_spin_order = max_spin_order
+        print(f"Maximum spin order set to: {self.max_spin_order}\n")
+
+    def build(self):
+        """
+        Builds the basis set for the spin system. Prior to building the basis,
+        the maximum spin order should be defined. If it is not defined, it is
+        set equal to the number of spins in the system (may be very slow)!
+        """
+        # If maximum spin order is not specified, raise a warning and set it
+        # equal to the number of spins
+        if self.max_spin_order is None:
+            warnings.warn("Maximum spin order not specified. "
+                          "Defaulting to the number of spins.")
+            self.max_spin_order = self._spin_system.nspins
+
+        # Build the basis
+        self._basis = make_basis(spins = self._spin_system.spins,
+                                 max_spin_order = self.max_spin_order)
+        
+    def truncate_by_coherence(
+            self,
+            coherence_orders: list,
+            *objs: np.ndarray | sp.csc_array
+        ) -> None | np.ndarray | sp.csc_array | tuple[np.ndarray | sp.csc_array]:
+        """
+        Truncates the basis set by retaining only the product operators that
+        correspond to coherence orders specified in the `coherence_orders` list.
+
+        Optionally, superoperators or state vectors can be given as input. These
+        will be converted to the truncated basis.
+
+        Parameters
+        ----------
+        coherence_orders : list
+            List of coherence orders to be retained in the basis.
+
+        Returns
+        -------
+        objs_transformed : ndarray or csc_array or tuple
+            Superoperators and state vectors transformed into the truncated
+            basis.
+        """
+        # Truncate the basis and obtain the index map
+        truncated_basis, index_map = truncate_basis_by_coherence(
+            basis = self.basis,
+            coherence_orders = coherence_orders
+        )
+
+        # Update the basis
+        self._basis = truncated_basis
+
+        # Optionally, convert the superoperators and state vectors to the
+        # truncated basis
+        if objs:
+            objs_transformed = []
+            for obj in objs:
+
+                # Consider state vectors
+                if isvector(obj):
+                    objs_transformed.append(state_to_truncated_basis(
+                        index_map=index_map,
+                        rho=obj))
+                    
+                # Consider superoperators
+                else:
+                    objs_transformed.append(sop_to_truncated_basis(
+                        index_map=index_map,
+                        sop=obj
+                    ))
+
+            # Convert to tuple or just single value
+            if len(objs_transformed) == 1:
+                objs_transformed = objs_transformed[0]
+            else:
+                objs_transformed = tuple(objs_transformed)
+
+            return objs_transformed

spinguin-0.0.1/src/spinguin/api/composite_spin_system.py

@@ -0,0 +1 @@
+# TODO