Attoworld Library for Attosecond Science

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: 'path/to/frog_trace.dat'

  cause The specified file path for the FROG trace is incorrect, or the file does not exist at the given location.
  fix Verify the absolute or relative path to your FROG trace file. Ensure the file exists and is accessible from where your script is run. Use `os.path.exists()` to check the path before attempting to load.

• TypeError: 'numpy.ndarray' object cannot be interpreted as a path

  cause The `FROG.load_trace()` method expects a string representing a file path, not a NumPy array containing the trace data directly.
  fix If you have your trace data as a NumPy array, you must first save it to a file format `attoworld` can read (e.g., a `.dat` file with appropriate headers), and then pass the path to that saved file to `load_trace()`.

• AttributeError: module 'attoworld.frog' has no attribute 'reconstruct_FROG_trace'

  cause Direct access to low-level reconstruction functions like `reconstruct_FROG_trace` is not the primary high-level API. Reconstruction is typically handled through the `FROG` class interface.
  fix Use the `FROG` class from `attoworld.frog.interface` and its `reconstruct` method, passing a `FROG_CONFIG` object for settings.

• error: can't find Rust compiler

  cause During `pip install attoworld` or when building from source, the system is missing the Rust compiler toolchain required for the performance-critical FROG core.
  fix Install the Rust toolchain using `rustup.rs`. For example, on Linux/macOS: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`. Ensure a C++ compiler (like GCC, Clang, or MSVC) is also installed.

Warnings

• breaking The units and phase convention for `.Speck.dat` files were updated in v2025.0.46. This change ensures consistency with specific scientific standards but may lead to discrepancies if re-analyzing data processed with earlier versions or if expecting the old conventions.
  Fix: If working with `.Speck.dat` files or data generated with `attoworld` versions prior to `v2025.0.46`, re-evaluate your analysis results and ensure compatibility with the updated unit and phase conventions. Consult documentation or new examples for verification.
• gotcha The core FROG reconstruction algorithm was rewritten in Rust (v2025.0.41) for significant performance improvements. While `pip install` generally handles this via pre-built wheels, users building from source or on uncommon platforms may encounter Rust compilation errors or need to ensure a Rust toolchain is installed.
  Fix: If `pip install attoworld` fails with errors related to Rust or `maturin`, ensure you have a compatible C++ compiler and the Rust toolchain installed (e.g., via `rustup`). For most users on standard platforms, pre-built wheels should work without manual Rust setup.
• gotcha Many functions within `attoworld` operate with implicit physical units (e.g., femtoseconds for time, PHz for frequency, nanometers for wavelength). Supplying data in mismatched units without proper conversion will lead to incorrect scientific results without necessarily raising Python errors.
  Fix: Always consult function documentation or example usage to confirm the expected units for input parameters and the units of returned values. Ensure all input data is converted to the required unit system before passing it to `attoworld` functions.

Install

• pip install attoworld Install stable version

Imports

• FROG

  from attoworld.frog.interface import FROG

• FROG_CONFIG

  from attoworld.frog.frog_config import FROG_CONFIG

• fourier_transform

  from attoworld.spectra import fourier_transform

• io

  import attoworld.io as aio

Quickstart

This quickstart demonstrates how to load a FROG trace from a file (or create a dummy one), configure the reconstruction settings using `FROG_CONFIG`, and perform a basic FROG reconstruction to obtain the reconstructed pulse intensity.

import numpy as np
import os
from attoworld.frog.interface import FROG
from attoworld.frog.frog_config import FROG_CONFIG

# 1. Create a dummy FROG trace file for demonstration
dummy_file_path = "dummy_frog_trace.dat"
delay_axis = np.linspace(-100, 100, 128) # fs
freq_axis = np.linspace(2.0, 4.0, 128) # PHz
dummy_trace = np.random.rand(128, 128) * 100 + 10 # Base noise
dummy_trace[40:80, 40:80] += 500 # Add a feature to the trace

with open(dummy_file_path, "w") as f:
    f.write("# FROG trace data\n")
    f.write(f"# delay_axis {delay_axis.min()} {delay_axis.max()} {len(delay_axis)}\n")
    f.write(f"# freq_axis {freq_axis.min()} {freq_axis.max()} {len(freq_axis)}\n")
    np.savetxt(f, dummy_trace)

# 2. Initialize FROG processor and load the trace
frog_processor = FROG()
frog_processor.load_trace(dummy_file_path)

# 3. Configure FROG reconstruction settings
config = FROG_CONFIG()
config.max_iter = 10 # Keep iterations low for quick execution
config.pulse_width_estimate_fs = 50
config.wavelength_center_nm = 800
config.delay_steps = len(delay_axis)
config.freq_steps = len(freq_axis)
config.delay_max = delay_axis.max()
config.delay_min = delay_axis.min()
config.freq_max = freq_axis.max()
config.freq_min = freq_axis.min()

# 4. Perform reconstruction
print("Starting FROG reconstruction...")
frog_processor.reconstruct(config)
print("Reconstruction complete.")

# 5. Access results
reconstructed_pulse_intensity = frog_processor.reconstructed_intensity
print(f"Reconstructed pulse intensity shape: {reconstructed_pulse_intensity.shape}")

# 6. Clean up the dummy file
os.remove(dummy_file_path)