fput 0.5.1

A Python package for simulating the Fermi-Pasta-Ulam-Tsingou problem

FPUT - Fermi-Pasta-Ulam-Tsingou Problem Simulator

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

pip install fput

For development:

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

Quick Start

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:

# 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:

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

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

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
• API Reference
• Theory Background

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 for guidelines.

License

This project is licensed under the MIT License - see the 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.