<!-- PROJECT SHIELDS -->

![Python version][python-version-url]

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 `