Warp-Bubble Shape Catalog

Catalog of candidate warp‐bubble shape functions

Created: May 29, 2025

This repository collects the defining formulas, support sizes, and key free parameters for 2 warp‐bubble "shape" profiles, Alcubierre's tanh‐based profile and Natário's smooth Gaussian variant.

Overview

This catalog serves as a reference repository documenting various mathematical functions used to define warp-bubble geometries in theoretical physics. Each profile is characterized by:

• Defining Formula: The mathematical expression that describes the shape function
• Support Size: The spatial extent over which the function is non-negligible
• Free Parameters: Adjustable parameters that control the shape characteristics

Documentation

A comprehensive Jekyll documentation site is available at:
https://arcticoder.github.io/warp-bubble-shape-catalog/

The documentation includes:

• Profiles: Detailed mathematical descriptions of each warp-bubble shape function
• Scripts: Complete documentation of all Python utilities with usage examples
• Visuals: Generated plots and visualizations of the profile functions

Contents

• scripts/
  Python scripts for plotting profiles, generating numeric data, computing support sizes, and exporting CSV.
• data/
  Supporting data or plots illustrating each profile.
• docs/
  Jekyll documentation site with detailed mathematical descriptions, script documentation, and visualizations.

Purpose

This catalog is designed as a dependency for downstream projects that will specify:

• Coordinate system choices (e.g., spherical coordinates $(t,r,\theta,\phi)$)
• Symmetry assumptions (e.g., axial symmetry about the $z$–axis, compact support in $r$)
• Metric ansatz simplifications

Data Availability

Numeric data for all profiles is available in multiple formats:

• NumPy format: data/profiles.npz (compressed binary)
• CSV format: data/profile_data.csv (human-readable)

These datasets contain discretized $(r, f(r))$ values for each profile function, generated using the provided Python scripts.

Scripts

All Python scripts reside in the scripts/ folder:

• plot_profiles.py
  Generate publication-quality plots of warp-bubble shape functions for visualization and analysis. Features configurable plot parameters, automatic high-DPI saving, and optional interactive display with command-line flags.
• generate_profile_data.py
  Generate high-resolution numeric data for all warp-bubble profiles and save in compressed binary format for efficient storage and loading.
• compute_support_size.py
  Estimate practical support sizes for each profile function given a specified threshold value. Provides console output with clear formatting.
• export_profiles_csv.py
  Export profile data to human-readable CSV format for analysis in external tools, spreadsheet applications, or other programming languages.

Usage Examples

1. Plot profiles with interactive display

   # Default: Interactive display + save plot
   python scripts/plot_profiles.py
   
   # Interactive display only (no file saved)
   python scripts/plot_profiles.py --interactive
   python scripts/plot_profiles.py -i
   
   # Save plot only (no interactive display)
   python scripts/plot_profiles.py --save-only
   python scripts/plot_profiles.py -s
   
   # Both interactive display and save plot
   python scripts/plot_profiles.py --both
   python scripts/plot_profiles.py -b
   ```   The interactive display allows you to zoom, pan, and explore the plot data. Saved plots go to:
   - `data/plots/profiles.png` (high-resolution visualization)
   - `docs/assets/images/profiles.png` (for Jekyll site display)
   
   Both files are saved in high-resolution PNG format (300 DPI).
   

2. Generate numeric data

   python scripts/generate_profile_data.py

   Creates data/profiles.npz with high-resolution $(r, f(r))$ values for all profiles.

3. Compute support sizes

   python scripts/compute_support_size.py

   Analyzes where each profile function falls below a threshold (default: $10^{-3}$) and reports practical support sizes.

4. Export to CSV

   python scripts/export_profiles_csv.py

   Creates data/profile_data.csv in human-readable format for use in Excel, MATLAB, R, or other analysis tools.

Dependencies

All scripts require:

• NumPy: Numerical computations
• Matplotlib: Plotting (plot_profiles.py only)

Install dependencies:

pip install numpy matplotlib

Repository Structure

warp-bubble-shape-catalog/
├── data/                             # Generated data and plots
│   ├── profiles.npz                  # Binary profile data
│   ├── profile_data.csv              # CSV profile data
│   └── plots/
│       └── profiles.png              # Generated visualization
├── scripts/                          # Python utilities
│   ├── plot_profiles.py              # Plotting and visualization
│   ├── generate_profile_data.py      # Data generation
│   ├── compute_support_size.py       # Support analysis
│   └── export_profiles_csv.py        # CSV export
└── docs/                             # Jekyll documentation site
    ├── _config.yml                   # Jekyll configuration
    ├── index.md                      # Documentation home
    ├── profiles.md                   # Profile descriptions
    ├── scripts.md                    # Script documentation
    ├── visuals.md                    # Visualization gallery
    └── assets/images/                # Site images
        └── profiles.png              # Copy for web display

Common Workflow

1. Generate all data and visualizations:

   python scripts/generate_profile_data.py
   python scripts/export_profiles_csv.py
   python scripts/plot_profiles.py

2. Analyze profile properties:

   python scripts/compute_support_size.py

3. Verify output files:

   • data/profiles.npz (binary data)
   • data/profile_data.csv (CSV data)
   • data/plots/profiles.png (high-resolution visualization)
   • docs/assets/images/profiles.png (visualization for Jekyll site)

Troubleshooting

GitHub Pages Image Display

If images don't appear on the GitHub Pages site, you may need to:

1. Verify file permissions: Make sure all image files have the proper permissions to be served
2. Check file paths: Ensure Jekyll configuration has correct baseurl and image paths
3. Force rebuild: In the GitHub repository settings under Pages, trigger a rebuild
4. Use relative paths: Try with both /assets/images/profiles.png and assets/images/profiles.png
5. Commit directly: Add the images directly through the GitHub interface

Interactive Plot Display

If interactive plotting fails with an error about missing Qt5 or Tk:

pip install PyQt5

Or use the non-interactive mode:

python scripts/plot_profiles.py -s

License

The Unlicense

Scope, Validation & Limitations

• Scope: The materials and numeric outputs in this repository are research-stage examples and depend on implementation choices, parameter settings, and numerical tolerances.
• Validation: Reproducibility artifacts (scripts, raw outputs, seeds, and environment details) are provided in docs/ or examples/ where available; reproduce analyses with parameter sweeps and independent environments to assess robustness.
• Limitations: Results are sensitive to modeling choices and discretization. Independent verification, sensitivity analyses, and peer review are recommended before using these results for engineering or policy decisions.