tasai 1.0.1
Autonomous Triple-Axis Spectroscopy using Active Learning
License: MIT
Requires Python: >=3.9
Keywords: neutron scattering, triple-axis spectrometer, autonomous experiments, active learning, Bayesian inference

# TAS-AI: Autonomous Triple-Axis Spectrometer Control

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**TAS-AI** is a Python framework for autonomous neutron scattering experiments on triple-axis spectrometers. It combines Bayesian inference, physics-informed models, and active learning to optimize measurement strategies in real-time.

Developed at the NIST Center for Neutron Research (NCNR).

## Why TAS-AI?

Traditional neutron scattering experiments require scientists to manually decide each measurement point—a slow, labor-intensive process. TAS-AI automates this by:

- **Learning from each measurement** to decide what to measure next
- **Using physics models** to focus on informative regions
- **Accounting for motor motion** to minimize dead time
- **Providing real-time visualization** of the experiment

Result: **2-5× faster** experiments with **fewer measurements**.

## Features

- 🎯 **Physics-Informed Acquisition**: Uses spin wave models to guide measurements
- 🔄 **Model Discrimination**: Bayesian comparison of competing Hamiltonians (e.g., NN vs J1-J2)
- 📊 **Real-Time Dashboard**: Live visualization of experiments with Textual TUI
- ⚡ **Motor Motion Optimization**: Minimizes dead time with intelligent path planning
- 🧮 **MCMC Inference**: Full Bayesian parameter estimation with BUMPS/emcee
- 🔬 **Sunny-Inspired Models**: Fast Python spin wave calculations
- 📈 **Benchmark Suite**: Compare against gpCAM, Log-GP, and grid methods

## Installation

### Option 1: Mamba/Conda (Recommended)

Mamba is significantly faster than conda for dependency resolution:

```bash
# Clone repository
git clone https://github.com/ncnr/tasai.git
cd tasai

# Create environment with mamba (fast)
mamba env create -f environment.yml
mamba activate tasai

# Or with conda (slower)
conda env create -f environment.yml
conda activate tasai
```

### Option 2: Pip

```bash
git clone https://github.com/ncnr/tasai.git
cd tasai
pip install -e ".[all]"
```

### Option 3: Docker

```bash
# Build image
docker build -t tasai .

# Run dashboard (accessible at http://localhost:8050)
docker run -p 8050:8050 tasai micromamba run -n tasai python dashboard/app.py --host 0.0.0.0

# Run examples
docker run tasai micromamba run -n tasai python examples/example_parameter_determination.py
```

### Verify Installation

```bash
python -c "import tasai; print('TAS-AI installed successfully!')"
```

## Quick Start

```bash
# Run dashboard demo
python dashboard/app.py --port 8050 --debug

# Run parameter estimation example
python examples/example_parameter_determination.py

# Run model discrimination example
python examples/example_model_discrimination.py

# Run order parameter example
python examples/order_parameter_simulation.py
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    TAS-AI Framework                         │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │  Dashboard  │  │   Physics   │  │     Inference       │ │
│  │  (Textual)  │  │   Models    │  │   (MCMC/Bayes)      │ │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
│         │                │                     │            │
│  ┌──────▼────────────────▼─────────────────────▼──────────┐│
│  │                  Acquisition Function                   ││
│  │         score = info_gain^η / (count + move)           ││
│  └──────────────────────────┬─────────────────────────────┘│
│                             │                               │
│  ┌──────────────────────────▼─────────────────────────────┐│
│  │              Instrument Interface                       ││
│  │    (Simulator / HTTP Proxy / Direct Control)           ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

## Documentation

- [User Manual](docs/MANUAL.md) - Complete guide for users
- [Dashboard Guide](docs/DASHBOARD.md) - Dashboard features and controls
- [Benchmarks](docs/BENCHMARKS.md) - Performance comparisons
- [Sunny Integration](docs/SUNNY.md) - Spin wave calculations
- [API Reference](docs/API.md) - Developer documentation

## Examples

| Example | Description |
|---------|-------------|
| `example_parameter_determination.py` | Determine J1, J2, D from spin wave data |
| `example_model_discrimination.py` | Test if J2 interactions are needed |
| `example_with_motor_motion.py` | Include motor motion in optimization |
| `order_parameter_simulation.py` | Phase transition (Tc, β) measurement |
| `benchmark_jcns.py` | Compare against JCNS Log-GP method |

## Comparison with Other Approaches

| Feature | TAS-AI | gpCAM (ILL) | Log-GP (JCNS) | ANDiE (ORNL) |
|---------|--------|-------------|---------------|--------------|
| Physics-informed | ✅ | ❌ | ❌ | ✅ |
| Model discrimination | ✅ | ❌ | ❌ | ✅ |
| Motor motion | ✅ | ❌ | ❌ | ❌ |
| Log-space GP | ✅ | ❌ | ✅ | ❌ |
| Real-time dashboard | ✅ | ❌ | ❌ | ❌ |

## Requirements

- Python 3.9+
- NumPy, SciPy, Matplotlib
- Textual (for dashboard)
- Optional: scikit-learn (for GP), emcee/bumps (for MCMC)
- Optional: Julia + Sunny.jl (for advanced spin wave calculations)

## Citation

If you use TAS-AI in your research, please cite:

```bibtex
@software{tasai2024,
  title = {TAS-AI: Autonomous Triple-Axis Spectrometer Control},
  author = {NIST Center for Neutron Research},
  year = {2024},
  url = {https://github.com/ncnr/tasai}
}
```

## Related Work

- [ANDiE](https://doi.org/10.1063/5.0082956) - Autonomous Neutron Diffraction Explorer
- [gpCAM](https://github.com/lbl-camera/gpCAM) - Gaussian Process Campaign
- [AutoREFL](https://github.com/ncnr/autorefl) - Autonomous Reflectometry
- [SpinW](https://spinw.org) - Spin Wave Calculation Library
- [Sunny.jl](https://github.com/SunnySuite/Sunny.jl) - Modern Spin Dynamics

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.