Quickstart Guide#

Welcome to the dolphin Quickstart Guide!

This guide will walk you through setting up the dolphin ecosystem for AI-automated strong lens modeling and generating your first model overview plots. By the end, you’ll be able to run a complete pipeline from raw data to a finished model.

1. Installation#

First, ensure you have Python installed. You will need dolphin, its underlying engine lenstronomy, and other necessary dependencies. You can install dolphin easily via pip:

pip install space-dolphin

2. Setting Up Your Workspace#

dolphin requires a structured workspace (input/output directory) to manage your data, configurations, and results. You can name this directory anything you like. For a complete example, take a look at the io_directory_example included in the repository.

Inside your workspace directory, create the following subdirectories. Note: These subdirectory names are fixed and must exactly match the ones below.

  • data: Stores subdirectories for each lens system. Inside each lens system’s folder, place: - Image data files (HDF5 format). - PSF files (HDF5 format).

  • settings: Stores the configuration files (config_{lens_name}.yaml) for each system. (See the Config Options Guide for detailed keyword options).

  • masks: (Optional) Stores custom mask files (mask_{lens_name}_{band}.npy) to override or guide the AI’s segmentation.

  • logs: Stores pipeline run logs.

  • outputs: Saves the final model outputs, including posteriors and reconstructed images.

  • hpc: (Optional) Stores scripts for submitting batch jobs on high-performance computing clusters (MPI environments).

Example Directory Structure:

my_dolphin_workspace/
├── data/
│   ├── system_name/
│   │   ├── image_system_name_band.h5  # Provided by you
│   │   ├── psf_system_name_band.h5    # Provided by you
├── settings/
│   ├── config_system_name.yaml        # Generated by AI or provided by you
│   ├── masks/
│   │   ├── mask_system_name_band.npy  # Generated by AI or provided by you
├── logs/
├── outputs/
├── hpc/

3. Formatting Image and PSF Data#

dolphin expects image and PSF files in HDF5 format, following the naming conventions used by lenstronomy.

The Image Data File MUST contain: - image_data: Reduced, background-subtracted image cutout centered on the lens. - background_rms: The background noise level. - exposure_time: A map of exposure times per pixel, such that image_data * exposure_time follows a Poisson noise distribution. - ra_at_xy_0: ΔRA (arcsec) of the (0, 0) pixel relative to the cutout center. - dec_at_xy_0: ΔDec (arcsec) of the (0, 0) pixel relative to the cutout center. - transform_pix2angle: A rotation and scaling matrix mapping pixel index differences (Δx, Δy) to angular differences (ΔRA, ΔDec) in arcseconds.

The PSF Data File MUST contain: - kernel_point_source: A pixelated Point Spread Function (PSF). - psf_variance_map: (Optional) A map of the uncertainty in the provided PSF (must match the PSF dimensions).

4. Running the Fully Automated AI Pipeline#

With your workspace set up, you can now run the dolphin AI pipeline! The following Python code demonstrates a complete run for a lensed quasar system:

from dolphin.ai import Vision, Modeler
from dolphin.processor import Processor

# 1. Point dolphin to your workspace
io_directory_path = "path/to/my_dolphin_workspace"

# 2. Vision: Generate the semantic segmentation mask
# We specify source_type="quasar" for lensed quasars (or "galaxy" for lensed galaxies)
vision = Vision(io_directory_path, source_type="quasar")
vision.create_segmentation_for_single_lens(
     lens_name="system_name",
     band_name="filter_name"
)

# 3. Modeler: Generate the lens configuration based on the AI mask
modeler = Modeler(io_directory_path, source_type="quasar")
modeler.create_config_for_single_lens(
     lens_name="system_name",
     band_name="filter_name"
)

# 4. Processor: Run the forward model using the generated configuration
processor = Processor(io_directory_path)
processor.swim(
     lens_name="system_name",
     model_id="my_first_model",
     recipe_name="galaxy-quasar"
)

Tip: Be sure to replace ``system_name`` and ``filter_name`` with your actual lens folder and band string!

5. Analyzing and Visualizing the Output#

Once the modeling is complete, you can find the detailed logs in your logs/ directory and the resulting data in the outputs/ directory.

To easily visualize the results, dolphin provides built-in plotting utilities:

from dolphin.analysis import Output

# Load the output workspace
output = Output(io_directory_path)

# Generate an overview plot for your specific model run
fig = output.plot_model_overview(
     lens_name="system_name",
     model_id="my_first_model"
)

# Save the plot for inspection
fig.savefig("my_first_model_overview.png")

Congratulations! 🎉 You have successfully set up the dolphin environment, utilized its AI capabilities for automated masking and configuration, and generated a complete forward model.

Next Steps & Examples#

  • Jupyter Notebooks: For hands-on tutorials, explore the notebooks folder in our repository.

  • Real-World Examples: Check out the “Project Dinos” GitHub repository. It contains numerous examples of manually curated config.yaml files used for semi-automated modeling in Tan et al. (2024).

  • Semi-Automated Tweaking: The AI generates an excellent starting point, but you can always open the generated config.yaml and manually tweak parameters before running processor.swim() to achieve even better fits.