Cleanup the featomic.utils namespace

Most of the code is now in `featomic.clebsch_gordan` instead

docs/src/references/api/python/clebsch-gordan.rst

@@ -0,0 +1,19 @@
+Clebsch-Gordan products
+=======================
+
+.. autoclass:: featomic.clebsch_gordan.PowerSpectrum
+    :members:
+
+.. autoclass:: featomic.clebsch_gordan.DensityCorrelations
+    :members:
+
+.. autofunction:: featomic.clebsch_gordan.cartesian_to_spherical
+
+
+Low-level functionalities
+-------------------------
+
+.. autoclass:: featomic.clebsch_gordan.ClebschGordanProduct
+    :members:
+
+.. autofunction:: featomic.clebsch_gordan.calculate_cg_coefficients

docs/src/references/api/python/index.rst

@@ -20,4 +20,4 @@ independently <install-python-lib>`. The functions and classes provided in
     basis
     splines
 
-    utils/index
+    clebsch-gordan

docs/src/references/api/python/misc.rst

@@ -16,4 +16,4 @@ Miscellaneous
 
 .. autofunction:: featomic.convert_hypers
 
-.. autofunction:: featomic.utils.hypers_to_json
+.. autofunction:: featomic.hypers_to_json

docs/src/references/api/torch/clebsch-gordan.rst

@@ -0,0 +1,19 @@
+Clebsch-Gordan products
+=======================
+
+.. autoclass:: featomic.torch.clebsch_gordan.PowerSpectrum
+    :members:
+
+.. autoclass:: featomic.torch.clebsch_gordan.DensityCorrelations
+    :members:
+
+.. autofunction:: featomic.torch.clebsch_gordan.cartesian_to_spherical
+
+
+Low-level functionalities
+-------------------------
+
+.. autoclass:: featomic.torch.clebsch_gordan.ClebschGordanProduct
+    :members:
+
+.. autofunction:: featomic.torch.clebsch_gordan.calculate_cg_coefficients

docs/src/references/api/torch/index.rst

@@ -27,7 +27,7 @@ of featomic are documented below for an usage from Python:
 
     systems
     calculators
-    utils/index
+    clebsch-gordan
 
 --------------------------------------------------------------------------------
 

featomic/build.rs

@@ -12,13 +12,18 @@ fn main() {
  *    This file is automatically generated from the featomic sources,          *
  *    using cbindgen. If you want to make change to this file (including       *
  *    documentation), make the corresponding changes in the rust sources       *
- *    in `featomic/src/c_api/*.rs`                                             *
+ *    in `featomic/src/c_api/`                                                 *
  * =========================================================================== */";
 
         let mut config: cbindgen::Config = Default::default();
         config.language = cbindgen::Language::C;
         config.cpp_compat = true;
-        config.includes = vec!["metatensor.h".into()];
+        config.no_includes = true;
+        config.sys_includes = vec![
+            "stdbool.h".into(),
+            "stdint.h".into(),
+            "metatensor.h".into()
+        ];
         config.include_guard = Some("FEATOMIC_H".into());
         config.include_version = false;
         config.documentation = true;

featomic/include/featomic.h

@@ -3,37 +3,15 @@
  *    This file is automatically generated from the featomic sources,          *
  *    using cbindgen. If you want to make change to this file (including       *
  *    documentation), make the corresponding changes in the rust sources       *
- *    in `featomic/src/c_api/*.rs`                                             *
+ *    in `featomic/src/c_api/`                                                 *
  * =========================================================================== */
 
 #ifndef FEATOMIC_H
 #define FEATOMIC_H
 
-#include <stdarg.h>
 #include <stdbool.h>
 #include <stdint.h>
-#include <stdlib.h>
-#include "metatensor.h"
-
-/**
- * Euler's constant
- */
-#define EULER 0.5772156649015329
-
-/**
- * Constant value for `ln(pi)`
- */
-#define LN_PI 1.1447298858494002
-
-/**
- * Constant value for `2 * sqrt(e / pi)`
- */
-#define TWO_SQRT_E_OVER_PI 1.8603827342052657
-
-/**
- * Constant value for `ln(2 * sqrt(e / pi))`
- */
-#define LN_2_SQRT_E_OVER_PI 0.6207822376352452
+#include <metatensor.h>
 
 /**
  * Status code used when a function succeeded

featomic/src/lib.rs

@@ -18,6 +18,7 @@
 pub mod types;
 pub use types::*;
 
+/// cbindgen:ignore
 pub mod math;
 
 #[cfg(feature="c-api")]

featomic/tests/data/lode-spherical-expansion.py

@@ -2,7 +2,7 @@
 
 import ase
 import numpy as np
-from ase import io  # noqa
+from ase import io  # noqa: F401
 
 from featomic import LodeSphericalExpansion
 from save_data import save_calculator_input, save_numpy_array

featomic/tests/data/soap-spherical-expansion.py

@@ -2,7 +2,7 @@
 
 import ase
 import numpy as np
-from ase import io  # noqa
+from ase import io  # noqa: F401
 
 from featomic import SphericalExpansion
 from save_data import save_calculator_input, save_numpy_array

python/featomic-torch/featomic/torch/clebsch_gordan.py

@@ -0,0 +1,89 @@
+import importlib
+import os
+import sys
+from typing import Any
+
+import metatensor.torch
+import torch
+
+import featomic.utils
+
+from .calculator_base import CalculatorModule
+from .system import System
+
+
+# For details what is happening here take a look an `featomic.torch.calculators`.
+
+# create the `_backend` module as an empty module
+spec = importlib.util.spec_from_loader(
+    "featomic.torch.clebsch_gordan._backend",
+    loader=None,
+)
+module = importlib.util.module_from_spec(spec)
+# This module only exposes a handful of things, defined here. Any changes here MUST also
+# be made to the `featomic/clebsch_gordan/_backend.py` file, which is used in
+# non-TorchScript mode.
+module.__dict__["BACKEND_IS_METATENSOR_TORCH"] = True
+
+module.__dict__["Labels"] = metatensor.torch.Labels
+module.__dict__["TensorBlock"] = metatensor.torch.TensorBlock
+module.__dict__["TensorMap"] = metatensor.torch.TensorMap
+module.__dict__["LabelsEntry"] = metatensor.torch.LabelsEntry
+
+module.__dict__["CalculatorBase"] = CalculatorModule
+module.__dict__["IntoSystem"] = System
+
+module.__dict__["TorchTensor"] = torch.Tensor
+module.__dict__["TorchModule"] = torch.nn.Module
+module.__dict__["TorchScriptClass"] = torch.ScriptClass
+module.__dict__["Array"] = torch.Tensor
+module.__dict__["DType"] = torch.dtype
+module.__dict__["Device"] = torch.device
+
+module.__dict__["torch_jit_is_scripting"] = torch.jit.is_scripting
+module.__dict__["torch_jit_export"] = torch.jit.export
+
+if os.environ.get("METATENSOR_IMPORT_FOR_SPHINX", "0") == "0":
+    module.__dict__["operations"] = metatensor.torch.operations
+else:
+    # FIXME: we can remove this hack once metatensor-operations v0.2.4 is released
+    module.__dict__["operations"] = None
+
+
+def is_labels(obj: Any):
+    return isinstance(obj, metatensor.torch.Labels)
+
+
+if os.environ.get("FEATOMIC_IMPORT_FOR_SPHINX") is None:
+    is_labels = torch.jit.script(is_labels)
+
+module.__dict__["is_labels"] = is_labels
+
+
+def check_isinstance(obj, ty):
+    if isinstance(ty, torch.ScriptClass):
+        # This branch is taken when `ty` is a custom class (TensorMap, …). since `ty` is
+        # an instance of `torch.ScriptClass` and not a class itself, there is no way to
+        # check if obj is an "instance" of this class, so we always return True and hope
+        # for the best. Most errors should be caught by the TorchScript compiler anyway.
+        return True
+    else:
+        assert isinstance(ty, type)
+        return isinstance(obj, ty)
+
+
+# register the module in sys.modules, so future import find it directly
+sys.modules[spec.name] = module
+
+# create a module named `featomic.torch.clebsch_gordan` using code from
+# `featomic.clebsch_gordan`
+spec = importlib.util.spec_from_file_location(
+    "featomic.torch.clebsch_gordan", featomic.clebsch_gordan.__file__
+)
+
+module = importlib.util.module_from_spec(spec)
+
+# override `featomic.torch.clebsch_gordan` (the module associated with the current file)
+# with the newly created module
+sys.modules[spec.name] = module
+spec.loader.exec_module(module)