{"id":8848,"library":"attoworld","title":"Attoworld Library for Attosecond Science","description":"The `attoworld` library provides essential tools for attosecond science, developed by the Attosecond science group at the Max Planck Institute of Quantum Optics. It offers functionalities for data acquisition, processing, and analysis in areas like FROG (Frequency-resolved optical gating) and time-frequency analysis. The library is actively maintained with frequent releases, often several per month or quarter, following a `YYYY.minor.patch` versioning scheme.","status":"active","version":"2026.1.2","language":"en","source_language":"en","source_url":"https://github.com/NickKarpowicz/Attoworld","tags":["physics","attosecond","spectroscopy","FROG","science","data-analysis"],"install":[{"cmd":"pip install attoworld","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"FROG","correct":"from attoworld.frog.interface import FROG"},{"symbol":"FROG_CONFIG","correct":"from attoworld.frog.frog_config import FROG_CONFIG"},{"symbol":"fourier_transform","correct":"from attoworld.spectra import fourier_transform"},{"symbol":"io","correct":"import attoworld.io as aio"}],"quickstart":{"code":"import numpy as np\nimport os\nfrom attoworld.frog.interface import FROG\nfrom attoworld.frog.frog_config import FROG_CONFIG\n\n# 1. Create a dummy FROG trace file for demonstration\ndummy_file_path = \"dummy_frog_trace.dat\"\ndelay_axis = np.linspace(-100, 100, 128) # fs\nfreq_axis = np.linspace(2.0, 4.0, 128) # PHz\ndummy_trace = np.random.rand(128, 128) * 100 + 10 # Base noise\ndummy_trace[40:80, 40:80] += 500 # Add a feature to the trace\n\nwith open(dummy_file_path, \"w\") as f:\n    f.write(\"# FROG trace data\\n\")\n    f.write(f\"# delay_axis {delay_axis.min()} {delay_axis.max()} {len(delay_axis)}\\n\")\n    f.write(f\"# freq_axis {freq_axis.min()} {freq_axis.max()} {len(freq_axis)}\\n\")\n    np.savetxt(f, dummy_trace)\n\n# 2. Initialize FROG processor and load the trace\nfrog_processor = FROG()\nfrog_processor.load_trace(dummy_file_path)\n\n# 3. Configure FROG reconstruction settings\nconfig = FROG_CONFIG()\nconfig.max_iter = 10 # Keep iterations low for quick execution\nconfig.pulse_width_estimate_fs = 50\nconfig.wavelength_center_nm = 800\nconfig.delay_steps = len(delay_axis)\nconfig.freq_steps = len(freq_axis)\nconfig.delay_max = delay_axis.max()\nconfig.delay_min = delay_axis.min()\nconfig.freq_max = freq_axis.max()\nconfig.freq_min = freq_axis.min()\n\n# 4. Perform reconstruction\nprint(\"Starting FROG reconstruction...\")\nfrog_processor.reconstruct(config)\nprint(\"Reconstruction complete.\")\n\n# 5. Access results\nreconstructed_pulse_intensity = frog_processor.reconstructed_intensity\nprint(f\"Reconstructed pulse intensity shape: {reconstructed_pulse_intensity.shape}\")\n\n# 6. Clean up the dummy file\nos.remove(dummy_file_path)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2025.0.46"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2025.0.41"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The specified file path for the FROG trace is incorrect, or the file does not exist at the given location.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'path/to/frog_trace.dat'"},{"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()`.","cause":"The `FROG.load_trace()` method expects a string representing a file path, not a NumPy array containing the trace data directly.","error":"TypeError: 'numpy.ndarray' object cannot be interpreted as a path"},{"fix":"Use the `FROG` class from `attoworld.frog.interface` and its `reconstruct` method, passing a `FROG_CONFIG` object for settings.","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.","error":"AttributeError: module 'attoworld.frog' has no attribute 'reconstruct_FROG_trace'"},{"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.","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.","error":"error: can't find Rust compiler"}]}