Advanced Topics

Backends and Performance

sandalwood is designed for high performance by abstracting key numerical operations to a flexible backend system. This allows the library to leverage optimized libraries like NumPy and PyTorch.

The Backend System

The backend.py module defines a set of static methods for common tensor operations (e.g., power, prod, dot). The neval method in MultivariateTaylorFunction automatically selects the appropriate backend class based on the input array type by calling get_backend(array).

get_backend returns the backend class (not an instance). Because all backend methods are @staticmethod, the class itself is the callable, so no object is constructed on each dispatch call.

NumPy Backend

This is the default backend and is used when the input to neval is a NumPy array. All operations are performed using NumPy’s highly optimized C and Fortran libraries, providing excellent performance for CPU-based computation.

Memory semantics

NumpyBackend.from_numpy(a, copy=True) (the default) always returns a fresh copy. Pass copy=False only when you need a zero-cost view and are certain no in-place mutation will occur.

PyTorch Backend

When a PyTorch Tensor is passed to neval, sandalwood automatically switches to the PyTorch backend. This provides two key advantages:

  • GPU Acceleration: PyTorch’s native CUDA support allows operations to be executed on an NVIDIA GPU, dramatically speeding up computations on large batches of data.

  • Vector and Matrix Operations: PyTorch’s backend is specifically optimized for deep learning, making it exceptionally fast for the types of vectorized operations used in sandalwood.

Device and gradient safety

TorchBackend.to_numpy handles all common failure modes that would otherwise cause opaque RuntimeError exceptions:

  • Autograd-tracked tensors (requires_grad=True): detached from the computation graph before conversion. A UserWarning is emitted.

  • Non-CPU tensors (CUDA, MPS, …): copied to CPU host before conversion. A UserWarning is emitted because this incurs a device-to-host transfer.

import torch
from sandalwood.backend import TorchBackend

# Safe: detaches and warns
t = torch.tensor([1.0, 2.0], requires_grad=True)
arr = TorchBackend.to_numpy(t)  # emits UserWarning

# Safe: moves to CPU and warns
t_gpu = torch.tensor([1.0, 2.0]).cuda()
arr = TorchBackend.to_numpy(t_gpu)  # emits UserWarning

Behavioural fixes vs previous versions

Scenario

Before

After

to_numpy on requires_grad tensor

RuntimeError

detach + UserWarning

to_numpy on CUDA tensor

RuntimeError

.cpu() + UserWarning

prod(axis=None)

TypeError

global reduction

atleast_2d on 0-D tensor

shape (1,)

shape (1, 1)

from_numpy default

zero-copy shared buffer

independent copy

COSY Backend (Fortran)

For maximum performance at extremely high orders (e.g., order 20+) or for specific differential algebraic operators like Poisson brackets and map composition, sandalwood provides a bridge to the COSY Infinity core.

  • High-Order Stability: COSY is globally recognized for its numerical stability in high-order Taylor expansions.

  • Symplectic Tracking: Optimized routines for particle tracking in accelerator physics.

  • O(1) Memory Management: Uses a raw Fortran stack for ultra-fast allocation and deallocation.

  • Thread-safety (Python layer): CosyIndexPool is protected by a threading.RLock; initialize_mtf is protected by a module-level RLock. The underlying Fortran routines are still single-threaded.

For more details on the COSY backend architecture, see COSY Infinity Backend Architecture.

Future Work

This section outlines potential future directions for sandalwood, ranging from incremental improvements to more ambitious features.

### Expanded Functionality

  • Automatic Differentiation (AD): Implement support for AD to allow for the computation of gradients, Jacobians, and Hessians of Taylor maps.

  • Advanced Elementary Functions: Add support for more advanced elementary functions, such as Bessel functions, gamma functions, and error functions.

  • Non-linear Equation Solver: Implement a solver for systems of non-linear equations using Taylor series methods (e.g., Newton’s method with high-order corrections).

### Improved User Experience

  • Symbolic API: Develop a more intuitive API for creating and manipulating Taylor maps, perhaps with a more “symbolic” feel.

  • Example Gallery: Create a “gallery” of examples in the documentation showcasing real-world applications of sandalwood in physics, engineering, and other fields.

  • Improved Error Messages: Add more detailed error messages and warnings to help users debug their code.