Metadata-Version: 2.4
Name: fput
Version: 0.3.1
Summary: A Python package for simulating the Fermi-Pasta-Ulam-Tsingou problem
Author-email: FPUT Project Contributors <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/fput
Project-URL: Documentation, https://fput.readthedocs.io
Project-URL: Repository, https://github.com/yourusername/fput
Project-URL: Bug Tracker, https://github.com/yourusername/fput/issues
Keywords: FPUT,Fermi-Pasta-Ulam,nonlinear dynamics,physics,computational physics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: matplotlib>=3.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: numpydoc>=1.2; extra == "docs"
Dynamic: license-file

# FPUT - Fermi-Pasta-Ulam-Tsingou Problem Simulator

![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![PyPI](https://img.shields.io/badge/PyPI-fput-orange)

A Python package for simulating the classic Fermi-Pasta-Ulam-Tsingou (FPUT) problem - one of the most famous problems in nonlinear dynamics and statistical mechanics.

## Background

The FPUT problem originated from a 1950s computer experiment at Los Alamos National Laboratory. Enrico Fermi, John Pasta, and Stan Ulam (with programmer Mary Tsingou) investigated a chain of nonlinear oscillators, expecting to observe thermalization (energy equipartition). Instead, they discovered a surprising recurrence phenomenon - the system returned almost exactly to its initial state after many cycles.

This unexpected result challenged the foundations of statistical mechanics and led to the development of soliton theory and chaos theory.

## Installation

```bash
pip install fput
```

For development:

```bash
git clone https://github.com/yourusername/fput.git
cd fput
pip install -e ".[dev]"
```

## Quick Start

```python
from fput import FPUTSimulator
import matplotlib.pyplot as plt

# Create a simulator with 32 particles, alpha=0.25
sim = FPUTSimulator(N=32, alpha=0.25, dt=0.05)

# Set initial condition: fundamental sine wave
sim.set_initial_mode(mode=1, amplitude=4)

# Run simulation for 160 fundamental periods
result = sim.run(total_time=160, save_interval=10)

# Visualize the results
from fput.visualization import FPUTVisualizer
viz = FPUTVisualizer(result.time_points, result.mode_energies)
viz.plot_energy_evolution(style="overlay")
plt.show()
```

## Features

- **Interactive GUI**: User-friendly graphical interface for real-time simulation and visualization
- **Multiple Nonlinearities**: Support for both α (quadratic) and β (quartic) nonlinear couplings
- **Numerical Integration**: Runge-Kutta 4 and Velocity Verlet integrators
- **Normal Mode Analysis**: Convert between physical and normal mode coordinates
- **Visualization**: Built-in plotting tools for energy evolution and recurrence analysis
- **Extensible**: Easy to customize for your research needs

## Graphical User Interface

The package includes an interactive GUI for exploring the FPUT problem visually:

### Launching the GUI

After installation:

```bash
# Method 1: Using the command
fput-gui

# Method 2: Using Python module
python -m fput.gui

# Method 3: Direct import
from fput.gui import main
main()
```

### GUI Features

- **Real-time plotting**: Watch energy evolution as the simulation runs
- **Interactive controls**: Adjust parameters, pause/resume, and reset
- **Multiple views**: Energy evolution, phase space, participation ratio, and heat maps
- **Quick presets**: Classic FPUT, weak nonlinearity, and strong nonlinearity configurations
- **FPUT recurrence detection**: Automatically identifies energy return to initial mode

## Examples

### Classic FPUT Experiment

Reproduce the original FPUT results:

```python
from fput import FPUTSimulator
from fput.visualization import FPUTVisualizer

sim = FPUTSimulator(N=32, alpha=0.25)
sim.set_initial_mode(mode=1, amplitude=4)
result = sim.run(total_time=160, save_interval=10)

viz = FPUTVisualizer(result.time_points, result.mode_energies)
viz.plot_energy_evolution(style="stacked")
```

### Beta Nonlinearity

```python
from fput import FPUTBetaSimulator

sim = FPUTBetaSimulator(N=32, beta=1.0)
sim.set_initial_mode(mode=1, amplitude=1.0)
result = sim.run(total_time=200)
```

### Energy Recurrence Analysis

```python
from fput.utils import find_recurrence_times

recurrences = find_recurrence_times(
    result.time_points,
    result.mode_energies[:, 0],
    initial_energy=result.mode_energies[0, 0]
)
print(f"Recurrence times: {recurrences}")
```

## Documentation

- [Full Documentation](https://fput.readthedocs.io)
- [API Reference](https://fput.readthedocs.io/api.html)
- [Theory Background](https://fput.readthedocs.io/theory.html)

## The Physics

The FPUT system consists of a chain of particles connected by nonlinear springs. The Hamiltonian is:

```
H = Σ(1/2 * P_k²) + 1/2 * Σ((Q_{k+1} - Q_k)²) + α/3 * Σ((Q_{k+1} - Q_k)³)
```

where:
- `Q_k` is the displacement of particle k
- `P_k` is the momentum of particle k
- `α` is the nonlinear coupling parameter

In normal mode coordinates, the system reveals the surprising energy sharing patterns that puzzled Fermi, Pasta, Ulam, and Tsingou.

## Contributing

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

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## References

1. Fermi, E., Pasta, J., & Ulam, S. (1955). Studies of Nonlinear Problems I. Los Alamos Report LA-1940.
2. Tsingou, M. (Original programmer, now properly recognized!)
3. Ford, J. (1992). The Fermi-Pasta-Ulam problem: Paradox turns discovery. Physics Reports, 213(5), 271-310.

## Acknowledgments

This package is dedicated to the memory of Enrico Fermi, John Pasta, Stan Ulam, and especially Mary Tsingou, whose computational work made the original discovery possible.
