Data

Tools

Indexes

Applications

Experiments

Open Source Science

PyStarshade

PyStarshade: Simulating High-Contrast Imaging of Exoplanets with Starshades - Published in JOSS (2025)

https://github.com/xiaziyna/pystarshade

Science Score: 93.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ✓
    DOI references
    Found 1 DOI reference(s) in JOSS metadata
  • ○
    Academic publication links
  • ○
    Academic email domains
  • ○
    Institutional organization owner
  • ✓
    JOSS paper metadata
    Published in Journal of Open Source Software

Scientific Fields

Engineering Computer Science - 32% confidence
Last synced: 6 months ago · JSON representation

Repository

PyStarshade is a Python library for efficient Fresnel optical simulations of direct imaging with an external occulter from stellar system to CCD

Basic Info
Statistics
  • Stars: 4
  • Watchers: 2
  • Forks: 4
  • Open Issues: 0
  • Releases: 1
Created almost 3 years ago · Last pushed 7 months ago
Metadata Files
Readme License

README.md

PyStarshade

License: GPL v3

Overview

Developed by Jamila Taaki (MIDAS fellow).

PyStarshade is a Python library for Starshade (or any external occulter) simulations from star-planet system to CCD with Fresnel diffraction methods. This library efficiently calculates output fields using Bluestein FFTs.

What is a starshade? A starshade is a particular apodization (mask), which flown at Fresnel distances from a telescope achieves star-light suppression for imaging exoplanets in orbit around the star.

Numerical diffraction calculations for a starshade must use a very small numerical resolution $d u$ of the starshade $s(u, v)$ in order to accurately calculate starlight suppression. Using a standard FFT to perform these calculations is inefficient as very large zero-padding factors are needed to sample the field at the telescope aperture. The Bluestein FFT is a technique to calculate arbitrary spectral samples of a propagated field, indirectly using FFTs and therefore benefiting from their efficiency. For an $N \cdot N$ starshade mask, and an $M \cdot M$ telescope aperture, the Bluestein FFT approach achieves a complexity of $O((N+M)^2 \log (M+N))$. This technique is utilized in multiple aspects of the optical train to efficiently propagate fields.

Example

Simulated imaging of a synthetic exoscene (ExoVista) with three visible exoplanets at a wavelength of 500 nm. A 60 m starshade configuration and a 6m segmented pupil was used for this example.

Three planets imaged with a HWO concept starshade and a 6m hexagonal segmented pupil.

Installation

For a barebones install, use pip:

bash pip install pystarshade

If you want to use pre-generated data instead install the package from source, in editable mode and use git lfs. This requires several GB of space:

bash $ git clone https://github.com/xiaziyna/PyStarshade.git PyStarshade $ cd PyStarshade $ git lfs pull pip install -e .

Dependencies

Scipy, Numpy, HCIPy, astropy, setuptools, pytest

Quickstart

Detailed documentation for all PyStarshade utilities.

Input data

PyStarshade can take as input any pixelized source-field such as Haystacks model, or analytic descriptions of sources (so far a point source and Gaussian source). If you wish to perform propagation using analytic descriptions, please use 'pystarshade.simulatefield.pointsourcetoccd'.

The easiest way to interface with PyStarshade is via the StarshadeProp class. Generate fields/psf models for a chosen design reference mission (drm). Simulate imaging for a 'source_field' with a default 2 mas sampling.

```python import numpy as np from pystarshade.propagator import StarshadeProp import matplotlib.pyplot as plt

1. Initialize the Starshade Propagator with HWO (Habitable Worlds Observatory) configuration

starshade = StarshadeProp(drm='hwo') # drm = design reference mission

2. Generate the pupil field (this handles the Fresnel diffraction from starshade to telescope)

starshade.genpupilfield()

3. Generate PSF basis for a hexagonal pupil (this handles the Fraunhofer diffraction to focal plane)

pupiltype = 'hex' starshade.genpsfbasis(pupiltype=pupil_type)

4. Create a simple point source (representing a star)

Using 2 mas (milliarcsecond) sampling as default

nx = ny = 100 # image size sourcefield = np.zeros((nx, ny), dtype=np.float32) sourcefield[nx//2, ny//2] = 1.0 # place a point source in the center

5. Generate the final image

wavelength = 500e-9 # 500 nm focalintensity = starshade.genscene(pupiltype, sourcefield, wavelength)

6. Visualize the result

plt.figure(figsize=(8, 8)) plt.imshow(focal_intensity, norm=plt.LogNorm()) plt.colorbar() plt.title('Simulated Starshade Image') plt.xlabel('Pixels') plt.ylabel('Pixels') plt.show() ```

Worked examples

See examples folder for different simulation examples.

Contributing

Feel free to reach out if you'd like to discuss contributing or go ahead and submit a pull request! Try to keep any pull requests limited in scope. If there is demand for extra functionality, I am happy to help add these in. See here for further instructions.

License

[PyStarshade] is released under the GNU General Public License v3.0.

Owner

  • Name: Jamila Taaki
  • Login: xiaziyna
  • Kind: user

PhD student at UIUC

JOSS Publication

PyStarshade: Simulating High-Contrast Imaging of Exoplanets with Starshades
Published
July 25, 2025
DOI
Volume 10, Issue 111, Page 7917
Authors
Jamila Taaki ORCID
Michigan Institute for Data Science, University of Michigan, USA
Athol Kemball ORCID
University of Illinois at Urbana-Champaign, USA, University of the Witwatersrand, Johannesburg, South Africa
Farzad Kamalabadi
University of Illinois at Urbana-Champaign, USA
Editor
Ivelina Momcheva ORCID
Tags
astronomy exoplanets starshades high-contrast imaging
View PDF Review Thread Software Archive

GitHub Events

Total
  • Issues event: 24
  • Watch event: 4
  • Issue comment event: 66
  • Push event: 173
  • Pull request event: 6
  • Fork event: 3
  • Create event: 5
Last Year
  • Issues event: 24
  • Watch event: 4
  • Issue comment event: 66
  • Push event: 173
  • Pull request event: 6
  • Fork event: 3
  • Create event: 5

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 17
  • Total pull requests: 9
  • Average time to close issues: 19 days
  • Average time to close pull requests: 27 days
  • Total issue authors: 3
  • Total pull request authors: 4
  • Average comments per issue: 2.41
  • Average comments per pull request: 0.78
  • Merged pull requests: 6
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 17
  • Pull requests: 9
  • Average time to close issues: 19 days
  • Average time to close pull requests: 27 days
  • Issue authors: 3
  • Pull request authors: 4
  • Average comments per issue: 2.41
  • Average comments per pull request: 0.78
  • Merged pull requests: 6
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • ivalaginja (9)
  • Jashcraf (7)
  • AFg6K7h4fhy2 (1)
Pull Request Authors
  • warrickball (3)
  • xiaziyna (2)
  • ivastar (2)
  • AFg6K7h4fhy2 (2)
Top Labels
Issue Labels
Pull Request Labels

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 10 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 5
  • Total maintainers: 1
pypi.org: pystarshade

A python package for starshade imaging simulations

  • Versions: 5
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 10 Last month
Rankings
Dependent packages count: 7.1%
Average: 19.9%
Dependent repos count: 32.6%
Maintainers (1)
xiaziyna
Last synced: 6 months ago