PASTIS

Sweet liquor from the south of France.

In this repo though, PASTIS is an algorithm for analytical contrast predictions of coronagraphs on segmented telescopes, developed and published in Leboulleux et al. (2018) and Laginja et al. (2021), and use for laboratory experiments in Laginja et al. (2022).

This readme provides quick instructions to get PASTIS results for the LUVOIR-A telescope, as well as more detailed info about the code and other telescopes it supports. For further info, contact the author under iva.laginja@obspm.fr.

Table of Contents

• Quickstart from template
  • Clone the repo and create conda environment
  • Set up local configfile
  • Create a PASTIS matrix and run a full analysis
  • Changing the input parameters
• Full Requirements
  • Git
  • Conda environment
  • Plotting
  • Known matplotlib issues on MacOS
• Configuration file
• Output directory
• PASTIS analysis
  • Rerunning just the analysis
• Supported Simulators
  • LUVOIR-A
  • LUVOIR-B
  • Habex
  • Luvex/HexRing
  • JWST
  • RST
  • HiCAT
• Jupyter notebooks
• About this repository
  • Contributing and code of conduct
  • Citing
  • License

Quickstart from template

This section will give you all the necessary terminal commands to go from opening this GitHub page in the browser to having reduced results of the template on your local machine.

We assume that you have conda and git installed and that you're using bash.

Clone the repo and create conda environment

• Navigate to the directory you want to clone the repository into:

$ cd /User/<YourUser>/repos/

• Clone the repository:

$ git clone https://github.com/spacetelescope/PASTIS.git

• Navigate into the cloned PASTIS repository:

$ cd PASTIS

• Create the pastis conda environment:

$ conda env create --file environment.yml

• Activate the environment:

$ conda activate pastis

• Install the package into this environment in develop mode

$ python setup.py develop

Set up local configfile

• Go into the code directory:

$ cd pastis

• Copy the file config_pastis.ini and name the copy config_local.ini.

• Open your local configfile config_local.ini and find the section [local]. In that section, define where all the output data will be saved to by adjusting the key local_data_path, e.g. (for more about the configfile, see Configuration file):

[local]
...
local_data_path = /Users/<user-name>/<path-to-data>

Save config_local.ini after these edits.

Create a PASTIS matrix and run a full analysis

• If not already activated, activate the pastis conda environment with $ conda activate pastis and get into the PASTIS/pastis/launchers subfolder.

• Create a PASTIS matrix and run the PASTIS analysis for the narrow-angle LUVOIR-A APLC design from the default template:

$ python run_luvoir.py

This will run for a couple of hours as the first thing that is generated is the PASTIS matrix. On a 13-in MacBook Pro 2020, the matrix gets calculated in about 80min, and the analysis runs in about 15 minutes. When it is done, you can inspect your results and log files in the path you specified under local_data_path in the section [local] of your config_local.ini!

Changing the input parameters

The default out-of-the-box analysis from the Quickstart section runs the following case:

• LUVOIR-A telescope
• narrow-angle ("small") Apodized Pupil Lyot Coronagraph (APLC)
• wavelength = 500 nm
• local aberration = piston
• calibration aberration per segment to generate the PASTIS matrix with: 1 nm

If you want to change any of these, please refer to the section about the configfile and Supported Simulators.

Full Requirements

Git

You will need git to clone this repository. Already a git user? Jump ahead. If not, please don't be that person who downloads the code and doesn't use version control. If you need a primer on git, see here. For the fastest ways to install git:

• To install it on a Mac, type git in your terminal and follow the instructions to install the Apple Xcode command tools.
• To make it easy on Windows, install Git Bash. Note: If you will use Git Bash with Miniconda (see below), you will have to add Miniconda to your PATH during setup, even if it is marked as not recommended. Otherwise, Git Bash can't access it.
• For Linux, follow this link.

Conda environment

We provide an environment.yml file that can be taken advantage of with the conda package management system. By creating a conda environment from this file, you will be set up to run all the code in this package.

If you don't know how to start with conda, you can download miniconda here. After a successful installation, you can create the pastis conda environment by navigating with the terminal into the PASTIS repository, where the environment.yml is located, and run:

$ conda env create --file environment.yml

This will create a conda environment called pastis that contains all the needed packages at the correct versions. If you want to give the environment a different name while it is getting created, you can run:

$ conda env create --name <env-name> --file environment.yml

where you have to replace <env-name> with your desired package name.

If you ever need to update your conda environment from the file environment.yml, you can do that with (where "pastis" is the environment name):

conda env update -n pastis -f environment.yml

You can also remove a conda environment with:

conda remove --name pastis --all

Plotting

There are certain things that the code is not controlling that are connected to plotting settings with matplotlib. Initially, the plotting should work as expected but the results might be slightly different from what is presented in the paper by Laginja et al. (2021), for example where matplotlib puts the image origin. If you want to use the lower left as your origin, this is adjustable in the plots directly by setting origin=lower, although I recommend adjusting your global plotting parameters in the matplotlibrc file so that you don't have to edit each plot manually.

In short, you can find the location of your rc file on disk by running:

>>> import matplotlib
>>> matplotlib.matplotlib_fname()
'/home/<some-path>/.config/matplotlib/matplotlibrc'

Opening up this file will show you a template rc file like described in the matplotlib documentation for these settings. To set your image origin permanently to the lower left for whenever you plot anything with matplotlib, search for image.origin within that file, delete the # which is commenting it out and set it to lower:

image.origin : lower

then save and close.

Known matplotlib issues on MacOS

While writing code for the repository, we ran into a couple of other issues with the plotting that were dependent on the OS and its version that we were using. If you run into the same issues, here is how we solved them:

On MacOS Catalina 10.15.5 - PDF font types

It does not support Type 3 PostScript fonts in PDF documents, while matplotlib uses Type 3 fonts by default. We got the error message:

The PDF backend does not currently support the selected font.

To mitigate this, go to your matplotlibrc file and make sure to uncomment and set:

pdf.fonttype       : 42

This will make it use Type 42 fonts instead. Instead of permanently editing you rc file, you can also drop in these two lines in the scripts concerned:

import matplotlib
matplotlib.rc('pdf', fonttype=42)

On MacOS Mojave 10.14.6 - backend

Using the tkagg backend on MacOS Mojave 10.14.6 makes the machine crash and restart, so don't use that one. The default should run fine, but if you encounter this issue you can change the default backend in the matplotlibrc file under backend at almost the very top of the file.

Configuration file

The main configuration file is config_pastis.ini, which holds all of your simulation parameters. This specific file, however, is version controlled, and the paths to local directories will get messed up if you push or pull this file; you might also lose the changes you made to the parameters. This is why config_pastis.ini is initially supposed to be used as a template.

In order to make it work for you, copy config_pastis.ini and rename the copy to config_local.ini. In this local configfile, you can set all your parameters, and it will override the config_pastis.ini at runtime. This means that if there is a config_local.ini, it will be used, if not, the code will fall back on config_pastis.ini. A copy of the used configfile is always saved together with the PASTIS matrix output when a matrix is generated. In the case you want to version control the configfile you use, we recommend that you fork the repository and simply use the config_pastis.ini file directly.

The first section deals with local paths. Here, you need to point the file to the directory you want to have the output data saved to:

[local]
...
local_data_path = /Users/<user-name>/data_from_repos/pastis_data

In the next section, you make a selection of the telescope you want to run the analysis on. See Supported Simulators to see what telescopes pastis currently supports.

[telescope]
name = LUVOIR

This name has to equal the section name of the configfile that specifies the telescope parameters. In the LUVOIR case, we have some parameters for the telescope itself, and for the coronagraph, as well as the operating wavelength.

[LUVOIR]
; aberration for matrix calculation, in NANOMETERS
calibration_aberration = 1.
; log10 limits of PASTIS validity in nm WFE
valid_range_lower = -4
valid_range_upper = 4

; telescope
nb_subapertures = 120
diameter = 15.
gaps = 0.02
optics_path_in_repo = data/LUVOIR_delivery_May2019/
aperture_path_in_optics = inputs/TelAp_LUVOIR_gap_pad01_bw_ovsamp04_N1000.fits
indexed_aperture_path_in_optics = inputs/TelAp_LUVOIR_gap_pad01_bw_ovsamp04_N1000_indexed.fits
lyot_stop_path_in_optics = inputs/LS_LUVOIR_ID0120_OD0982_no_struts_gy_ovsamp4_N1000.fits

; coronagraph
; iwa and owa from dictionaries within files. could move that to util.

; the coro size is not used automatically in the functions, it is always defined (or read from here) manually
coronagraph_size = small
lambda = 500.
sampling = 4.

The number of subapertures will not change, the diameter and gaps are in units of meters. The key optics_path_in_repo specifies the data location (within the repository) of the files that define the LUVOIR telescope: aperture, Lyot stop and APLC designs.There are three APLC designs available, with a small, medium and large FPM, and the key coronagraph_size lets you switch between them. Finally, lambda sets the wavelength in nanometers. The three keys below optics_path_in_repo are paths within the optics path that point to different files needed by the LUVOIR simulator.

The calibration_aberration is the local aberration coefficient that will be used when calculating the PASTIS matrix, and the two parameters below set the upper and lower log limits of the total pupil WFE rms value for which the hockey stick curve will be calculated.

Finally, there is a section defining how we count our Zernikes, and the calibration section defines the local aberration used on each segment, by the numbering defined in the [zernikes] section (not shown in README).

[calibration]
local_zernike = 1

Output directory

Each time a new PASTIS matrix is generated, this will create a new data folder in the directory you specified in the section [local] with the key local_data_path. These data folders will be of the form 2020-01-13T21-34-29_luvoir-small, capturing date and time of the start of the matrix generation, the telescope name, and for LUVOIR the APLC choice.

The code will copy the used configfile into this data folder, together with all results and log files. The data directory structure is as follows:

Note: Not all outputs are generated at the same time and through the same scripts. The below list captures all potential outputs written to disk.

|-- 2020-11-20T21-34-29_example
|   |-- coronagraph_floor.txt                    # E2E DH average contrast for unaberrated pupil
|   |-- full_report.pdf                          # a PDF file summarizing all results after analysis is run
|   |-- matrix_numerical
|       |-- config_local.ini                     # copy of the configfile used for matrix generation
|       |-- contrast_matrix.pdf                  # PDF image of the half-filled contrast matrix, before it is transformed into the PASTIS matrix
|       |-- efield_coron_imag.fits               # fits cube of the imaginary part of all injected aberrations as recorded in E-field in the science plane, with "n_modes" number of 2D arrays
|       |-- efield_coron_real.fits               # fits cube of the real part of all injected aberrations as recorded in E-field in the science plane, with "n_modes" number of 2D arrays
|       |-- efield_obwfs_imag.fits               # fits cube of the imaginary part of all injected aberrations as recorded in E-field in the WFS plane, with "n_modes" number of 2D arrays
|       |-- efield_obwfs_real.fits               # fits cube of the real part of all injected aberrations as recorded in E-field in the WFS plane, with "n_modes" number of 2D arrays
|       |-- OTE_images
|           |-- opd[...].pdf                     # PDF images of each segment pair aberration in the pupil
|           |-- ...
|      |-- contrast_matrix.fits:                 # contrast matrix - E2E DH average contrasts per aberrated segment pair (only half of it since it is symmetric), contrast floor is NOT subtracted
|      |-- contrast_matrix.pdf:                  # PDF image of contrast matrix
|      |-- pastis_matrix_example.log             # logging output of matrix calculation
|      |-- pastis_matrix.pdf                     # PDF image of the calculated PASTIS matrix 
|      |-- pastis_matrix.fits                    # the PASTIS matrix
|      |-- psfs
|          |-- psf_cube.fits                     # an image cube of the PSF from each segment pair aberration
|   |-- pastis_analysis.log:                     # logging output of the PASTIS analysis; new runs get appended
|   |-- ref_e0_coron.fits                        # unaberrated E-field in the science plane, real and imaginary parts as cube
|   |-- ref_e0_wfs.fits                          # unaberrated E-field in the WFS plane, real and imaginary parts as cube
|   |-- results
|       |-- [...].pdf/.txt                       # all results from the PASTIS analysis, including the modes
|       |-- ...
|   |-- title_page.pdf                           # title page of the full_report PDF file 
|   |-- unaberrated_coro_psf.fits                # image of unaberrated DH from E2E simulator
|   |-- unaberrated_coro_psf.pdf                 # PDF image of unaberrated DH from E2E simulator

PASTIS analysis

Rerunning just the analysis

Calculating the PASTIS matrix takes some time, but once this is over the PASTIS analysis can be redone on it without having to regenerate the matrix. To do this, open the script run_luvoir.py and comment out the line that calls the matrix calculation function:

    #run_matrix.calc()

and instead uncomment the line where you can pre-define the data directory, and drop in the correct folder directory within your output destination:

    dir_small = os.path.join(CONFIG_PASTIS.get('local', 'local_data_path'), '<your-data-directory_small>')

If you now run run_luvoir.py, it will only rerun the analysis.

Supported Simulators

pastis currently supports E2E simulators for several telescopes: LUVOIR-A, LUVOIR-B, Habex, JWST, RST and HiCAT. Only LUVOIR-A, LUVOIR-B and Habex come with a built-in E2E simulator within pastis. The simulator for JWST and RST is webbpsf and can be installed additionally, while the HiCAT simulator is currently private. The analysis for each of them can be started with the respective launcher in pastis/launchers.

LUVOIR-A

There is a built-in LUVOIR-A simulator readily usable within the pastis package, and it supports the three baseline APLC designs for this observatory. The script run_luvoir.py is pre-set to easily run the medium and large design APLCs of LUVOIR-A as well. You just need to uncomment the according lines and it will generate the matrices, and run the PASTIS analysis for those cases as well.

LUVOIR-B

The LUVOIR-B simulator runs with a Vortex coronagraph and is otherwise set up with the same deformable mirrors like LUVOIR-A, as it uses the built-in simulation infrastructure.

Habex

The Habex simulator is monolithic, has a Vortex coronagraph and uses the same global deformable mirrors like LUVOIR. It uses the built-in simulation infrastructure.

Luvex / HexRing

This simulator produces an aperture with a varying number of hexagonal segment rings with appropriate APLC designs. It uses the built-in simulation infrastructure.

JWST

The coronagraphs currently supported on JWST are the NIRCam coronagraphs. You will need to install webbpsf (installation instructions here) in order to be able to use it with pastis, and don't forget that you also need to install the required data files. Once you are done with the installation, you will also need to drop in your local path to your new webbpsf data files to the PASTIS configfile. You can figure out the path to your webbpsf data by running the following in a python session:

import webbpsf
webbpsf.utils.get_webbpsf_data_path()

Then you need to copy the output to the (local) configfile in the following section:

[local]
; figure out webbpsf-data path with: webbpsf.utils.get_webbpsf_data_path()
webbpsf_data_path = ...

The launcher for a JWST analysis is also located in pastis/launchers, as run_jwst.py.

RST

The simulator for the Roman Space Telescope is connected from webbpsf.

HiCAT

The HiCAT simulator is private and its support is only provided for internal use.

HiCAT-PASTIS compatible conda env:

1. Clone the PASTIS repo
2. Create a hicat env with a custom as described in https://github.com/spacetelescope/hicat-package#installation
3. $ conda activate <env-name>
4. $ pip uninstall pastis
5. $ cd ../PASTIS
6. $ git checkout develop
7. $ python setup.py develop
8. $ conda uninstall hcipy
9. $ conda install -c conda-forge hcipy=0.4
10. $ conda install -c conda-forge pypdf2
11. $ conda install -c conda-forge progressbar2
12. $ pip install fpdf

Jupyter notebooks

The directory "notebooks" contains a suite of notebooks that were used to develop the code on the repository. Their numbering refers to the order they were generated in and exist mostly for easier identification. The notebooks are not necessarily kept up to date with the main code in the pastis package.

About this repository

Contributing and code of conduct

Please read CONTRIBUTING.md for contribution guidelines, and the process for submitting issues and pull requests to us. Please also see our CODE OF CONDUCT.md.

Citing

If you use this code in your work, please find citation snippets to give us credit with in CITING.md.

License

This project is licensed under the BSD-3-Clause-License - see the LICENSE.md file for details.

Acknowledgments

Big thanks to Robel Geda (@robelgeda) for testing, checking and providing suggestions for the repo setup, quickstart and README.
We acknowledge Garreth Ruane for providing the Habex and LUVOIR-B coronagraph data.
We acknowledge the Segmented aperture coronagraph design and analysis (SCDA) team for the Luvex/SCDA simulator data (JPL/GSFC/STScI). Credits for the sensitivity analyses in the WFS plane and temporal analyses go to Laurent Pueyo and Ananya Sahoo.