cubie 0.0.2__tar.gz

cubie-0.0.2/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: cubie
+Version: 0.0.2
+Summary: CUDA Batch Integration Engine - for doing a lot at once.
+Author: Chris Cameron
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ccam80/cubie.git
+Project-URL: Issues, https://github.com/https://github.com/ccam80/cubie/issues
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: src/LICENSE
+Requires-Dist: numpy==1.26.4
+Requires-Dist: numba
+Requires-Dist: numba-cuda[cu12]
+Requires-Dist: attrs
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-durations; extra == "dev"
+Requires-Dist: pytest-json-report; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: cupy-cuda12x; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Provides-Extra: cupy
+Requires-Dist: cupy-cuda12x; extra == "cupy"
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == "pandas"
+Provides-Extra: all
+Dynamic: license-file
+
+# CuBIE
+## CUDA batch integration engine for python
+
+[![docs](https://github.com/ccam80/smc/actions/workflows/documentation.yml/badge.svg)](https://github.com/ccam80/smc/actions/workflows/documentation.yml) [![CUDA tests](https://github.com/ccam80/cubie/actions/workflows/ci_cuda_tests.yml/badge.svg)](https://github.com/ccam80/cubie/actions/workflows/ci_cuda_tests.yml)  [![Python Tests](https://github.com/ccam80/cubie/actions/workflows/ci_nocuda_tests.yml/badge.svg)](https://github.com/ccam80/cubie/actions/workflows/ci_nocuda_tests.yml)  [![test build](https://github.com/ccam80/cubie/actions/workflows/test_pypi.yml/badge.svg)](https://github.com/ccam80/cubie/actions/workflows/test_pypi.yml)
+
+A batch integration system for systems of ODEs and SDEs, for when elegant solutions fail and you would like to simulate 
+1,000,000 systems, fast. This package was designed to simulate a large electrophysiological model as part of a 
+likelihood-free inference method (eventually, package [cubism]), but the machinery is domain-agnostic.
+
+The most basic use case is to define a system of ODEs or SDEs, and then call cubie.solve(system, inits, params, duration) with a description of the "batch" in the form of initial conditions and system parameters. There are a few seconds of overhead in the first call to Solve - cubie really shines when dealing with large problems or repeated calls with a similarly sized batch.
+
+Defining a system of ODEs is the most cumbersome part of using this library. Like in MATLAB or SciPy, we need to create a dxdt function that takes the current state and parameters, and returns the rate of change of the state. Unlike MATLAB and SciPy, this function needs to be CUDA-compatible, which means it cannot use some of the features of Python and numpy. Creating a system is done by subclassing cubie.SystemModel.GenericODE, and implementing the dxdt method. See ThreeCM.py for an example of a small system. Fabbri_linder.py for an example of a large system.
+
+## Installation:
+pip install cubie
+
+## System Requirements:
+- Python 3.8 or later
+- CUDA Toolkit 12.9 or later
+- NVIDIA GPU with compute capability 6.0 or higher (i.e. GTX10-series or newer)
+
+I am using this library as a way to experiment with and learn about some better software practice than I have used in 
+past, including testing, CI/CD, and other helpful tactics I stumble upon. As such, while it's in development, there will
+be some clunky bits.
+
+The interface is not yet stable, and the documentation is currently non-working AI-generated slop, but the library now works roughly as you might expect, and can get up and running quickly by reading docstrings. Documentation and SymPy integration (as a means to get Jacobians to use implicit algorithms) are on the hit list for v0.1.0.
+## Project Goals:
+
+- Make an engine and interface for batch integration that is close enough to MATLAB or SciPy that a Python beginner can
+  get integrating with the documentation alone in an hour or two. This also means staying Windows-compatible.
+- Perform integrations of 10 or more parallel systems faster than MATLAB or SciPy can
+- Enable extraction of summary variables only (rather than saving time-domain outputs) to facilitate use in algorithms 
+  like likelihood-free inference.
+- Be extensible enough that users can add their own systems and algorithms without needing to go near the core machinery.
+- Don't be greedy - allow the user to control VRAM usage so that cubie can run alongside other applications.
+
+## Non-Goals:
+- Have the full set of integration algorithms that SciPy and MATLAB have.
+  The full set of known and trusted algorithms is long, and it includes many wrappers for old Fortran libraries that the Numba compiler can't touch. If a problem requires a specific algorithm, we can add it as a feature request, but we won't set out to implement them all.
+- Have a GUI.
+  MATLABs toolboxes are excellent, but from previous projects (specifically CuNODE, the precursor to cubie), GUI development becomes all-consuming and distracts from the purpose of the project.

cubie-0.0.2/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where    = ["src"]
+exclude  = ["./tests/*"]
+
+[project]
+name = "cubie"
+version = "0.0.2"
+description = "CUDA Batch Integration Engine - for doing a lot at once."
+authors = [
+    { name="Chris Cameron" }
+]
+readme = "readme.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["src/LICEN[CS]E*"]
+dependencies = [
+    "numpy==1.26.4",
+    "numba",
+    "numba-cuda[cu12]",
+    "attrs"
+]
+
+[project.urls]
+Homepage = "https://github.com/ccam80/cubie.git"
+Issues = "https://github.com/https://github.com/ccam80/cubie/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "pytest-durations",
+    "pytest-json-report",
+    "flake8",
+    "cupy-cuda12x",
+    "pandas"
+
+]
+cupy = [
+    "cupy-cuda12x",
+]
+pandas = [
+    "pandas"
+]
+all = []
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+testpaths = [
+    "tests"
+]
+markers = [
+    "nocudasim: Will fail if run on the GPU simulator, only test on real GPU",
+    "cupy: Requires optional dependency CuPy, will fail if not installed",
+    "slow: Marks tests that are slow to run, can be skipped with -m 'not slow'",
+]
+addopts = [
+    "--import-mode=importlib",
+    "-ra",
+    "--cov=cubie",
+    "--cov-report=xml:coverage.xml",
+    "--cov-report=term-missing",
+    "--json-report",
+    "--json-report-file=tests/pytest_report.json",
+]
+filterwarnings = [
+    "ignore::numba.core.errors.NumbaPerformanceWarning",
+]
+
+[tool.coverage.run]
+#source = ["cubie"]
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*"
+]
+relative_files = true
+
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]
+ignore_errors = true
+show_missing = true
+
+[tool.coverage.html]
+directory = "htmlReport"

cubie-0.0.2/readme.md

@@ -0,0 +1,41 @@
+# CuBIE
+## CUDA batch integration engine for python
+
+[![docs](https://github.com/ccam80/smc/actions/workflows/documentation.yml/badge.svg)](https://github.com/ccam80/smc/actions/workflows/documentation.yml) [![CUDA tests](https://github.com/ccam80/cubie/actions/workflows/ci_cuda_tests.yml/badge.svg)](https://github.com/ccam80/cubie/actions/workflows/ci_cuda_tests.yml)  [![Python Tests](https://github.com/ccam80/cubie/actions/workflows/ci_nocuda_tests.yml/badge.svg)](https://github.com/ccam80/cubie/actions/workflows/ci_nocuda_tests.yml)  [![test build](https://github.com/ccam80/cubie/actions/workflows/test_pypi.yml/badge.svg)](https://github.com/ccam80/cubie/actions/workflows/test_pypi.yml)
+
+A batch integration system for systems of ODEs and SDEs, for when elegant solutions fail and you would like to simulate 
+1,000,000 systems, fast. This package was designed to simulate a large electrophysiological model as part of a 
+likelihood-free inference method (eventually, package [cubism]), but the machinery is domain-agnostic.
+
+The most basic use case is to define a system of ODEs or SDEs, and then call cubie.solve(system, inits, params, duration) with a description of the "batch" in the form of initial conditions and system parameters. There are a few seconds of overhead in the first call to Solve - cubie really shines when dealing with large problems or repeated calls with a similarly sized batch.
+
+Defining a system of ODEs is the most cumbersome part of using this library. Like in MATLAB or SciPy, we need to create a dxdt function that takes the current state and parameters, and returns the rate of change of the state. Unlike MATLAB and SciPy, this function needs to be CUDA-compatible, which means it cannot use some of the features of Python and numpy. Creating a system is done by subclassing cubie.SystemModel.GenericODE, and implementing the dxdt method. See ThreeCM.py for an example of a small system. Fabbri_linder.py for an example of a large system.
+
+## Installation:
+pip install cubie
+
+## System Requirements:
+- Python 3.8 or later
+- CUDA Toolkit 12.9 or later
+- NVIDIA GPU with compute capability 6.0 or higher (i.e. GTX10-series or newer)
+
+I am using this library as a way to experiment with and learn about some better software practice than I have used in 
+past, including testing, CI/CD, and other helpful tactics I stumble upon. As such, while it's in development, there will
+be some clunky bits.
+
+The interface is not yet stable, and the documentation is currently non-working AI-generated slop, but the library now works roughly as you might expect, and can get up and running quickly by reading docstrings. Documentation and SymPy integration (as a means to get Jacobians to use implicit algorithms) are on the hit list for v0.1.0.
+## Project Goals:
+
+- Make an engine and interface for batch integration that is close enough to MATLAB or SciPy that a Python beginner can
+  get integrating with the documentation alone in an hour or two. This also means staying Windows-compatible.
+- Perform integrations of 10 or more parallel systems faster than MATLAB or SciPy can
+- Enable extraction of summary variables only (rather than saving time-domain outputs) to facilitate use in algorithms 
+  like likelihood-free inference.
+- Be extensible enough that users can add their own systems and algorithms without needing to go near the core machinery.
+- Don't be greedy - allow the user to control VRAM usage so that cubie can run alongside other applications.
+
+## Non-Goals:
+- Have the full set of integration algorithms that SciPy and MATLAB have.
+  The full set of known and trusted algorithms is long, and it includes many wrappers for old Fortran libraries that the Numba compiler can't touch. If a problem requires a specific algorithm, we can add it as a feature request, but we won't set out to implement them all.
+- Have a GUI.
+  MATLABs toolboxes are excellent, but from previous projects (specifically CuNODE, the precursor to cubie), GUI development becomes all-consuming and distracts from the purpose of the project.

cubie-0.0.2/setup.cfg

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

cubie-0.0.2/src/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Cameron
+
+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.

cubie-0.0.2/src/cubie/CUDAFactory.py

@@ -0,0 +1,227 @@
+"""Base classes for constructing cached CUDA device functions with Numba."""
+from typing import Set
+from abc import ABC, abstractmethod
+import attrs
+
+from cubie._utils import in_attr, is_attrs_class
+
+
+class CUDAFactory(ABC):
+    """Factory for creating and caching CUDA device functions.
+
+    Subclasses implement :meth:`build` to construct Numba CUDA device functions
+    or other cached outputs. Compile settings are stored as attrs classes and
+    any change invalidates the cache to ensure functions are rebuilt when
+    needed.
+
+    Attributes
+    ----------
+    _compile_settings : attrs class or None
+        Current compile settings.
+    _cache_valid : bool
+        Indicates whether cached outputs are valid.
+    _device_function : callable or None
+        Cached CUDA device function.
+    _cache : attrs class or None
+        Container for additional cached outputs.
+
+    Notes
+    -----
+    There is potential for a cache mismatch when doing the following:
+
+    ```python
+    device_function = self.device_function  # calls build if settings updated
+    self.update_compile_settings(new_setting=value)  # updates settings but
+    does not rebuild
+
+    device_function(argument_derived_from_new_setting)  # this will use the
+    old device function, not the new one
+    ```
+
+    The lesson is: Always use CUDAFactory.device_function at the point of
+    use, otherwise you'll defeat the cache invalidation logic.
+
+    If your build function returns multiple cached items, create a cache
+    class decorated with @attrs.define. For example:
+    ```python
+    @attrs.define
+    class MyCache:
+        device_function: callable
+        other_output: int
+    ```
+    Then, in your build method, return an instance of this class:
+    ```python
+
+    def build(self):
+        return MyCache(device_function=my_device_function,
+                        other_output=42)
+    ```
+
+    The current cache validity can be checked using the `cache_valid` property,
+    which will return True if the cache
+    is valid and False otherwise.
+    """
+
+    def __init__(self):
+        self._compile_settings = None
+        self._cache_valid = True
+        self._device_function = None
+        self._cache = None
+
+    @abstractmethod
+    def build(self):
+        """Build and return the CUDA device function.
+
+        This method must be overridden by subclasses.
+
+        Returns
+        -------
+        callable or attrs class
+            Compiled CUDA function or container of cached outputs.
+        """
+        return None
+
+    def setup_compile_settings(self, compile_settings):
+        """Attach a container of compile-critical settings to the object.
+
+        Parameters
+        ----------
+        compile_settings : attrs class
+            Settings object used to configure the CUDA function.
+
+        Notes
+        -----
+        Any existing settings are replaced.
+        """
+        if not attrs.has(compile_settings):
+            raise TypeError(
+                    "Compile settings must be an attrs class instance.")
+        self._compile_settings = compile_settings
+        self._invalidate_cache()
+
+    @property
+    def cache_valid(self):
+        """bool: ``True`` if cached outputs are up to date."""
+
+        return self._cache_valid
+
+    @property
+    def device_function(self):
+        """Return the compiled CUDA device function.
+
+        Returns
+        -------
+        callable
+            Compiled CUDA device function.
+        """
+        if not self._cache_valid:
+            self._build()
+        return self._device_function
+
+    @property
+    def compile_settings(self):
+        """Return the current compile settings object."""
+        return self._compile_settings
+
+    def update_compile_settings(
+        self, updates_dict=None, silent=False, **kwargs
+    ) -> Set[str]:
+        """Update compile settings with new values.
+
+        Parameters
+        ----------
+        updates_dict : dict, optional
+            Mapping of setting names to new values.
+        silent : bool, default=False
+            Suppress errors for unrecognised parameters.
+        **kwargs
+            Additional settings to update.
+
+        Returns
+        -------
+        set[str]
+            Names of settings that were successfully updated.
+
+        Raises
+        ------
+        ValueError
+            If compile settings have not been set up.
+        KeyError
+            If an unrecognised parameter is supplied and ``silent`` is ``False``.
+        """
+        if updates_dict is None:
+            updates_dict = {}
+        if kwargs:
+            updates_dict.update(kwargs)
+        if updates_dict == {}:
+            return set()
+
+        if self._compile_settings is None:
+            raise ValueError(
+                    "Compile settings must be set up using self.setup_compile_settings before updating.")
+
+        recognized_params = []
+
+        for key, value in updates_dict.items():
+            if in_attr(key, self._compile_settings):
+                setattr(self._compile_settings, key, value)
+                recognized_params.append(key)
+
+        unrecognised_params = set(updates_dict.keys()) - set(recognized_params)
+
+        if unrecognised_params and not silent:
+            invalid = ", ".join(sorted(unrecognised_params))
+            raise KeyError(
+                    f"'{invalid}' is not a valid compile setting for this "
+                    "object, and so was not updated.", )
+        if recognized_params:
+            self._invalidate_cache()
+
+        return set(recognized_params)
+
+    def _invalidate_cache(self):
+        """Mark cached outputs as invalid."""
+        self._cache_valid = False
+
+    def _build(self):
+        """Rebuild cached outputs if they are invalid."""
+        build_result = self.build()
+
+        # Multi-output case
+        if is_attrs_class(build_result):
+            self._cache = build_result
+            # If 'device_function' is in the dict, make it an attribute
+            if in_attr('device_function', build_result):
+                self._device_function = build_result.device_function
+        else:
+            self._device_function = build_result
+
+        self._cache_valid = True
+
+    def get_cached_output(self, output_name):
+        """Return a named cached output.
+
+        Parameters
+        ----------
+        output_name : str
+            Name of the cached item to retrieve.
+
+        Returns
+        -------
+        Any
+            Cached value associated with ``output_name``.
+
+        Raises
+        ------
+        KeyError
+            If ``output_name`` is not present in the cache.
+        """
+        if not self.cache_valid:
+            self._build()
+        if output_name == 'device_function':
+            return self._device_function
+        else:
+            if not in_attr(output_name, self._cache):
+                raise KeyError(
+                        f"Output '{output_name}' not found in cached outputs.")
+            return getattr(self._cache, output_name)

cubie-0.0.2/src/cubie/__init__.py

@@ -0,0 +1,21 @@
+"""
+cubie: CUDA Batch Integration Engine
+"""
+
+from importlib.metadata import version
+
+from cubie.batchsolving import *
+from cubie.integrators import  *
+from cubie.outputhandling import *
+from cubie.memory import *
+import cubie.systemmodels as systems
+from cubie._utils import *
+
+__all__ = ["summary_metrics", "default_memmgr", "systems", "ArrayTypes",
+           "Solver", "solve_ivp"]
+
+try:
+    __version__ = version("cubie")
+except ImportError:
+    # Package is not installed
+    __version__ = "unknown"