Refactor ase-ace Python interface for consistency and clarity

- Remove redundant ACECalculatorLazy class (ACECalculator already lazy)
- Make ACECalculator inherit from ACECalculatorBase with NotImplementedError
  stubs for cutoff/species/n_basis/get_descriptors (socket protocol limitation)
- Extract duplicate neighbor grouping logic to _group_neighbors() helper
- Fix mutable default argument in ACELibraryCalculator.calculate()
- Fix misleading threading docstring in batch_energy_forces_virial()
- Add __repr__ methods to all three calculator classes
- Update README with per-calculator parameter tables and descriptor docs
- Document ase_ace.utils helper functions
- Remove empty [ipi] optional dependency from pyproject.toml

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jameskermode

export/ase-ace/README.md

@@ -50,7 +50,7 @@ Install the required Julia packages in the ase-ace Julia environment:
 
 ```bash
 # Navigate to the ase-ace directory
-cd path/to/ACEpotentials.jl/ase-ace
+cd path/to/ACEpotentials.jl/export/ase-ace
 
 # Install Julia dependencies
 julia --project=julia -e '
@@ -85,10 +85,9 @@ pip install -e ".[dev]"
 ```
 
 **Installation options:**
-- `ase-ace` - Base package only
+- `ase-ace` - Base package only (includes `ACECalculator`)
 - `ase-ace[julia]` - Adds `juliacall` and `juliapkg` for `ACEJuliaCalculator`
 - `ase-ace[lib]` - Adds `matscipy` for `ACELibraryCalculator`
-- `ase-ace[ipi]` - For `ACECalculator` (no extra Python deps, just Julia)
 - `ase-ace[all]` - All optional dependencies
 
 ## Quick Start
@@ -169,21 +168,75 @@ print(f"Energy: {energy:.4f} eV")
 
 **Note**: Install with library support: `pip install ase-ace[lib]`
 
+## Computing ACE Descriptors
+
+The `get_descriptors()` method returns the raw ACE basis vectors for each atom,
+useful for fitting, analysis, and transfer learning.
+
+**Availability:** `ACEJuliaCalculator` and `ACELibraryCalculator` only.
+`ACECalculator` does not support descriptors (socket protocol limitation).
+
+### Example
+
+```python
+from ase.build import bulk
+from ase_ace import ACELibraryCalculator
+
+atoms = bulk('Si', 'diamond', a=5.43) * (2, 2, 2)
+calc = ACELibraryCalculator("deployment/lib/libace_model.so")
+
+# Get descriptors for all atoms
+descriptors = calc.get_descriptors(atoms)
+print(f"Shape: {descriptors.shape}")  # (natoms, n_basis)
+
+# Access model properties
+print(f"Cutoff: {calc.cutoff} Å")
+print(f"Species: {calc.species}")  # Atomic numbers
+print(f"Basis size: {calc.n_basis}")
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cutoff` | float | Cutoff radius in Angstroms |
+| `species` | List[int] | Supported atomic numbers |
+| `n_basis` | int | Number of basis functions per atom |
+
+### Use Cases
+
+- **Linear model verification**: For linear ACE, `E = sum(descriptors @ weights)`
+- **Transfer learning**: Use descriptors as features for other ML models
+- **Analysis**: Examine local atomic environments
+
 ## Configuration
 
-### Constructor Parameters
+### ACECalculator Parameters
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `model_path` | str | required | Path to ACE model JSON file |
-| `num_threads` | int/str | 'auto' | Julia threads: 1, 2, 4, 8, or 'auto' |
-| `port` | int | 0 | TCP port (0 = auto-assign) |
-| `unixsocket` | str | None | Unix socket name (faster for local) |
-| `timeout` | float | 60.0 | Connection timeout in seconds |
-| `julia_executable` | str | 'julia' | Path to Julia executable |
-| `julia_project` | str | None | Julia project path (default: bundled) |
+| `num_threads` | int/str | 'auto' | Julia threads |
+| `port` | int | 0 | TCP port (0 = auto) |
+| `unixsocket` | str | None | Unix socket name |
+| `timeout` | float | 60.0 | Connection timeout (seconds) |
+| `julia_executable` | str | 'julia' | Path to Julia |
+| `julia_project` | str | None | Julia project path |
 | `log_level` | str | 'WARNING' | Logging level |
 
+### ACEJuliaCalculator Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_path` | str | required | Path to ACE model JSON file |
+| `num_threads` | int/str | 'auto' | Julia threads |
+
+### ACELibraryCalculator Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `library_path` | str | required | Path to compiled .so file |
+
 ### Threading
 
 The calculator uses Julia's multi-threading for parallel ACE evaluation:
@@ -360,6 +413,29 @@ If using a specific port that's in use:
 calc = ACECalculator('model.json', port=0)  # Auto-assign port
 ```
 
+## Utility Functions
+
+The `ase_ace.utils` module provides helper functions for Julia setup:
+
+```python
+from ase_ace.utils import find_julia, check_julia_version, setup_julia_environment
+
+# Find Julia executable
+julia_path = find_julia()
+
+# Check Julia version
+major, minor, patch = check_julia_version()
+
+# Set up Julia environment with required packages
+setup_julia_environment(verbose=True)
+```
+
+**Available functions:**
+- `find_julia()` - Locate Julia executable in PATH
+- `check_julia_version(julia_executable)` - Get Julia version as (major, minor, patch) tuple
+- `check_julia_packages(julia_executable, julia_project)` - Check if required packages are installed
+- `setup_julia_environment(julia_executable, julia_project, verbose)` - Install and configure Julia dependencies
+
 ## Running Tests
 
 ```bash

export/ase-ace/pyproject.toml

@@ -42,9 +42,6 @@ julia = [
     "juliapkg>=0.1.10",
 ]
 
-# ACECalculator - i-PI socket backend (no extra Python deps, just Julia install)
-ipi = []
-
 # Development dependencies
 dev = [
     "pytest>=7.0",

export/ase-ace/src/ase_ace/base.py

@@ -17,9 +17,9 @@ class ACECalculatorBase(Calculator, ABC):
     Abstract base class for ACE calculators.
 
     Provides a unified API across different backends:
-    - ACELibraryCalculator (compiled .so via ctypes)
-    - ACEJuliaCalculator (JuliaCall)
-    - ACECalculator (socket-based, partial support)
+    - ACELibraryCalculator (compiled .so via ctypes) - full support
+    - ACEJuliaCalculator (JuliaCall) - full support
+    - ACECalculator (socket-based) - energy/forces/stress only, no descriptors
 
     Subclasses must implement the abstract properties and methods.
 

export/ase-ace/src/ase_ace/calculator.py

@@ -13,14 +13,16 @@
 from pathlib import Path
 from typing import Optional, Union, List
 
-from ase.calculators.calculator import Calculator, all_changes
+import numpy as np
+from ase.calculators.calculator import all_changes
 
+from .base import ACECalculatorBase
 from .server import JuliaACEServer, find_free_port
 
 logger = logging.getLogger(__name__)
 
 
-class ACECalculator(Calculator):
+class ACECalculator(ACECalculatorBase):
     """
     ASE calculator for ACE potentials via Julia/IPICalculator.
 
@@ -78,7 +80,6 @@ class ACECalculator(Calculator):
     IPICalculator.jl installed.
     """
 
-    implemented_properties = ['energy', 'forces', 'stress']
     default_parameters = {}
 
     def __init__(
@@ -92,7 +93,7 @@ def __init__(
         julia_project: Optional[str] = None,
         log_level: str = 'WARNING',
     ):
-        Calculator.__init__(self)
+        super().__init__()
 
         # Configure logging
         logging.basicConfig(level=getattr(logging, log_level.upper()))
@@ -183,7 +184,7 @@ def calculate(self, atoms=None, properties=None, system_changes=all_changes):
         if properties is None:
             properties = self.implemented_properties
 
-        Calculator.calculate(self, atoms, properties, system_changes)
+        super().calculate(atoms, properties, system_changes)
 
         # Start server on first calculation
         if not self._started:
@@ -237,13 +238,43 @@ def actual_port(self) -> Optional[int]:
         """The actual TCP port being used (after start)."""
         return self._actual_port
 
+    # Abstract method implementations (not supported for socket-based calculator)
 
-class ACECalculatorLazy(ACECalculator):
-    """
-    Lazy-initialized ACECalculator.
+    @property
+    def cutoff(self) -> float:
+        """Cutoff radius in Angstroms."""
+        raise NotImplementedError(
+            "cutoff not available for socket-based ACECalculator. "
+            "Use ACEJuliaCalculator or ACELibraryCalculator instead."
+        )
 
-    Same as ACECalculator but delays Julia startup until the first
-    calculation is requested. This is the default behavior of
-    ACECalculator.
-    """
-    pass
+    @property
+    def species(self) -> List[int]:
+        """List of supported atomic numbers."""
+        raise NotImplementedError(
+            "species not available for socket-based ACECalculator. "
+            "Use ACEJuliaCalculator or ACELibraryCalculator instead."
+        )
+
+    @property
+    def n_basis(self) -> int:
+        """Number of basis functions per atom."""
+        raise NotImplementedError(
+            "n_basis not available for socket-based ACECalculator. "
+            "Use ACEJuliaCalculator or ACELibraryCalculator instead."
+        )
+
+    def get_descriptors(self, atoms) -> np.ndarray:
+        """
+        Compute ACE descriptors (basis values) for all atoms.
+
+        Not supported for socket-based ACECalculator.
+        Use ACEJuliaCalculator or ACELibraryCalculator instead.
+        """
+        raise NotImplementedError(
+            "get_descriptors() not available for socket-based ACECalculator. "
+            "Use ACEJuliaCalculator or ACELibraryCalculator instead."
+        )
+
+    def __repr__(self) -> str:
+        return f"ACECalculator(model={self.model_path.name}, threads={self.num_threads})"

export/ase-ace/src/ase_ace/julia_calculator.py

@@ -240,8 +240,7 @@ def calculate(
             properties = self.implemented_properties
 
         # Call parent to set self.atoms
-        from ase.calculators.calculator import Calculator
-        Calculator.calculate(self, atoms, properties, system_changes)
+        super().calculate(atoms, properties, system_changes)
 
         self._ensure_initialized()
         jl = self._jl
@@ -339,3 +338,6 @@ def get_descriptors(self, atoms) -> np.ndarray:
         )(at_jl, self._model)
 
         return np.array(descriptors_jl)
+
+    def __repr__(self) -> str:
+        return f"ACEJuliaCalculator(model={self.model_path.name}, threads={self._num_threads})"

export/ase-ace/src/ase_ace/library_calculator.py

@@ -17,7 +17,7 @@
 from pathlib import Path
 from typing import Optional, List
 
-from ase.calculators.calculator import Calculator, all_changes
+from ase.calculators.calculator import all_changes
 
 from .base import ACECalculatorBase
 
@@ -189,7 +189,7 @@ def batch_energy_forces_virial(
         """
         Compute energies, forces, and virials for multiple atoms.
 
-        Uses threading when JULIA_NUM_THREADS > 1.
+        Note: Threading is NOT available in --trim=safe compiled libraries.
         """
         natoms = len(z)
         total_neighbors = len(neighbor_z)
@@ -282,16 +282,14 @@ class ACELibraryCalculator(ACECalculatorBase):
     >>> print(f"Energy: {atoms.get_potential_energy():.4f} eV")
     """
 
-    implemented_properties = ['energy', 'forces', 'stress']
-
     def __init__(self, library_path: str, **kwargs):
         if not HAS_MATSCIPY:
             raise ImportError(
                 "matscipy is required for ACELibraryCalculator. "
                 "Install it with: pip install matscipy"
             )
 
-        Calculator.__init__(self, **kwargs)
+        super().__init__(**kwargs)
         self.ace = ACELibrary(library_path)
 
     @property
@@ -309,6 +307,30 @@ def n_basis(self) -> int:
         """Number of basis functions (descriptors per atom)."""
         return self.ace.n_basis
 
+    def _group_neighbors(self, i_idx: np.ndarray, natoms: int) -> tuple:
+        """
+        Group neighbor list by center atom.
+
+        Parameters
+        ----------
+        i_idx : np.ndarray
+            Center atom indices from neighbor list
+        natoms : int
+            Total number of atoms
+
+        Returns
+        -------
+        tuple
+            (atom_starts, atom_ends) arrays indicating neighbor ranges
+        """
+        if len(i_idx) > 0:
+            atom_starts = np.searchsorted(i_idx, np.arange(natoms))
+            atom_ends = np.searchsorted(i_idx, np.arange(natoms), side='right')
+        else:
+            atom_starts = np.zeros(natoms, dtype=int)
+            atom_ends = np.zeros(natoms, dtype=int)
+        return atom_starts, atom_ends
+
     def get_descriptors(self, atoms) -> np.ndarray:
         """
         Compute ACE descriptors (basis values) for all atoms.
@@ -353,12 +375,7 @@ def get_descriptors(self, atoms) -> np.ndarray:
         )
 
         # Group neighbors by center atom
-        if len(i_idx) > 0:
-            atom_starts = np.searchsorted(i_idx, np.arange(natoms))
-            atom_ends = np.searchsorted(i_idx, np.arange(natoms), side='right')
-        else:
-            atom_starts = np.zeros(natoms, dtype=int)
-            atom_ends = np.zeros(natoms, dtype=int)
+        atom_starts, atom_ends = self._group_neighbors(i_idx, natoms)
 
         # Compute descriptors for each atom
         descriptors = np.zeros((natoms, self.n_basis), dtype=np.float64)
@@ -379,13 +396,16 @@ def get_descriptors(self, atoms) -> np.ndarray:
 
         return descriptors
 
-    def calculate(self, atoms=None, properties=['energy'], system_changes=all_changes):
+    def calculate(self, atoms=None, properties=None, system_changes=all_changes):
         """
         Perform calculation for given atoms object.
 
-        Uses matscipy neighbor list and batch API with threading.
+        Uses matscipy neighbor list and site-level API.
         """
-        Calculator.calculate(self, atoms, properties, system_changes)
+        if properties is None:
+            properties = self.implemented_properties
+
+        super().calculate(atoms, properties, system_changes)
 
         natoms = len(atoms)
         numbers = atoms.get_atomic_numbers()
@@ -398,12 +418,7 @@ def calculate(self, atoms=None, properties=['energy'], system_changes=all_change
         )
 
         # Group neighbors by center atom
-        if len(i_idx) > 0:
-            atom_starts = np.searchsorted(i_idx, np.arange(natoms))
-            atom_ends = np.searchsorted(i_idx, np.arange(natoms), side='right')
-        else:
-            atom_starts = np.zeros(natoms, dtype=int)
-            atom_ends = np.zeros(natoms, dtype=int)
+        atom_starts, atom_ends = self._group_neighbors(i_idx, natoms)
 
         neighbor_counts = (atom_ends - atom_starts).astype(np.int32)
 
@@ -466,3 +481,6 @@ def calculate(self, atoms=None, properties=['energy'], system_changes=all_change
                 self.results['stress'] = stress
             else:
                 self.results['stress'] = np.zeros(6)
+
+    def __repr__(self) -> str:
+        return f"ACELibraryCalculator(lib={self.ace.lib_path.name})"