# WebbPSF Extensions
## Extending JWST PSF generation
[](https://pypi.python.org/pypi/webbpsf_ext)
*Authors*: Jarron Leisenring (U. of Arizona, Steward Observatory)
`webbpsf_ext` provides some enhancements to the [WebbPSF](https://webbpsf.readthedocs.io) package for PSF creation. This follows the [pyNRC](https://github.com/JarronL/pynrc) implementation for storing and retrieving JWST PSFs. In particular, this module generates and saves polynomial coefficients to quickly create unique instrument PSFs as a function of wavelength, focal plane position, and wavefront error drift from thermal distortions.
More specifically, `webbpsf_ext` uses WebbPSF to generate a series of monochromatic PSF simulations, then produces polynomial fits to each pixel. Storing the coefficients rather than a library of PSFS allows for quick creation (via matrix multiplication) of PSF images for an arbitrary number of wavelengths (subject to hardware memory limitations). The applications range from quickly creating PSFs for many different stellar types over wide bandpasses to generating a large number of monochromatic PSFs for spectral dispersion.
In addition, each science instrument PSF is dependent on the detector position due to field-dependent wavefront errors. Such changes are tracked in WebbPSF, but it becomes burdensome to generate new PSFs from scratch at each location, especially for large starfields. Instead, these changes can be stored by the fitting the residuals of the PSF coefficients across an instrument's field of view, then interpolating for an arbitrary location. A similar scheme can be achieved for coronagraphic occulters, where the PSF changes as the source position moves with respect to the mask.
JWST's thermal evolution (e.g., changing the angle of the sunshield after slewing to a new target) causes small but significant distortions to the telescope backplane. WebbPSF has tools to modify OPDs, but high-fidelity simulations take time to calculate. Since the change to the PSF coefficients varies smoothly with respect to WFE drift components, it's simple to parameterize the coefficient residuals in a fashion similar to the field-dependence.
## `webbpsf_ext` classes
Currently, only NIRCam and MIRI instrument classes are supported via the `NIRCam_ext` and `MIRI_ext` objects (although other instruments can be similarly implemented), which subclass the native `NIRCam` and `MIRI` objects found in WebbPSF. The key functions to call and generate PSF coefficients are:
1. `gen_psf_coeff`: Creates a set of coefficients that will generate simulated PSFs for any arbitrary wavelength. This function first simulates a number of evenly- spaced PSFs throughout the specified bandpass (or the full channel). An nth-degree polynomial is then fit to each oversampled pixel using a linear-least squares fitting routine. The final set of coefficients for each pixel is returned as an image cube. The returned set of coefficient are then used to produce PSF via `calc_psf_from_coeff`. Useful for quickly generated imaging and dispersed PSFs for multiple spectral types.
1. `gen_wfedrift_coeff`: This function finds a relationship between PSF coefficients in the presence of WFE drift. For a series of WFE drift values, we generate corresponding PSF coefficients and fit a polynomial relationship to the residual values. This allows us to quickly modify a nominal set of PSF image coefficients to generate a new PSF where the WFE has drifted by some amplitude.
1. `gen_wfefield_coeff`: Science instruments generally have field-dependent wavefront errors, which have been carefully measured in ground-based cryovac test campaigns ([SI WFE](https://webbpsf.readthedocs.io/en/latest/jwst.html#si-wfe)). These aberrations are expected to be static throughout the JWST mission lifetime. Similar to the above function, we generate PSF coefficients at each of the sampled positions and create a `RegularGridInterpolator` function to quickly determine new coefficient residuals at arbitrary locations.
1. `gen_wfemask_coeff`: For coronagraphic masks, slight changes in the PSF location relative to the image plane mask can substantially alter the PSF speckle pattern. This function generates a number of PSF coefficients at a variety of positions, then fits polynomials to the residuals to track how the PSF changes across the mask's field of view. Special care is taken near the 10-20mas region in order to provide accurate sampling of the SGD offsets.
## Installing with pip
Download via pip:
```bash
pip install webbpsf_ext
```
## Installing from source
To get the most up to date version of `webbpsf_ext`, install directly from the GitHub source.
In this case, you will need to clone the git repository:
```bash
git clone https://github.com/JarronL/webbpsf_ext
```
Then install the package with:
```bash
cd webbpsf_ext
pip install .
```
For development purposes, you can use editable installations:
```bash
cd webbpsf_ext
pip install -e .
```
This is useful for helping to develop the code, creating bug reports, switching between branches and submitting pull requests to GitHub. Since the code then lives in your local GitHub directory, this method makes it simple to pull the latest updates straight from the GitHub repo, which are then immediately available to python at runtime without needing to reinstall.
## Create Data Directory
You can define the directory that stores the PSF coefficients by setting the environment variable `WEBBPSF_EXT_PATH` to point to some data directory. All PSF coefficients will be saved here as they are generated to be reused later. For example, in `.bashrc` shell file, add:
```bash
export WEBBPSF_EXT_PATH='$HOME/data/webbpsf_ext_data/'
```
If this is not set, then a `psf_coeff` sub-directory is created in the already existing `WEBBPSF_PATH` directory.
## Synphot Data Directory
If you have not already done so, you will need to provide a data files for the required `synphot` and `stsynphot` packages . These are used to generate the monochromatic PSFs and to calculate the throughput of the instrument. Data files for Synphot are distributed through the
[Calibration Reference Data System](https://www.stsci.edu/hst/instrumentation/reference-data-for-calibration-and-tools). They are expected to follow a certain directory structure under the root directory, identified by the ``PYSYN_CDBS`` environment variable that *must* be
set prior to using this package.
1. Download [cdbs.tar.gz](https://arizona.box.com/shared/static/cbkxlwvokml7n1gref8nw3neg98kzcwn.gz) [approx. 900 MB] to obtain the full set of Synphot data files. Or download a minimum subset of files [here](https://arizona.box.com/shared/static/wgq7ymqsp8e7jfno8yk6o2igbnqlad8z.zip) [approx 50 MB].
2. Untar into a directory of your choosing.
3. Set the environment variable ``PYSYN_CDBS`` to point to that directory. For example, in .bashrc shell file, add:
```bash
export PYSYN_CDBS='$HOME/data/cdbs/'
```
After re-sourcing your shell, you should now be able to successfully ``import synphot, stsynphot`` in a Python session.
Raw data
{
"_id": null,
"home_page": "https://github.com/JarronL/webbpsf_ext",
"name": "webbpsf-ext",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "jwst psf nircam miri simulation",
"author": "Jarron Leisenring",
"author_email": "jarronl@arizona.edu",
"download_url": "https://files.pythonhosted.org/packages/52/95/fa74509cf11df5c2ff6670d292bdb1c6dcf211904987f9ee43562b5d3c39/webbpsf_ext-1.2.3.tar.gz",
"platform": null,
"description": "# WebbPSF Extensions\n\n## Extending JWST PSF generation\n\n[](https://pypi.python.org/pypi/webbpsf_ext)\n\n*Authors*: Jarron Leisenring (U. of Arizona, Steward Observatory)\n\n`webbpsf_ext` provides some enhancements to the [WebbPSF](https://webbpsf.readthedocs.io) package for PSF creation. This follows the [pyNRC](https://github.com/JarronL/pynrc) implementation for storing and retrieving JWST PSFs. In particular, this module generates and saves polynomial coefficients to quickly create unique instrument PSFs as a function of wavelength, focal plane position, and wavefront error drift from thermal distortions.\n\nMore specifically, `webbpsf_ext` uses WebbPSF to generate a series of monochromatic PSF simulations, then produces polynomial fits to each pixel. Storing the coefficients rather than a library of PSFS allows for quick creation (via matrix multiplication) of PSF images for an arbitrary number of wavelengths (subject to hardware memory limitations). The applications range from quickly creating PSFs for many different stellar types over wide bandpasses to generating a large number of monochromatic PSFs for spectral dispersion.\n\nIn addition, each science instrument PSF is dependent on the detector position due to field-dependent wavefront errors. Such changes are tracked in WebbPSF, but it becomes burdensome to generate new PSFs from scratch at each location, especially for large starfields. Instead, these changes can be stored by the fitting the residuals of the PSF coefficients across an instrument's field of view, then interpolating for an arbitrary location. A similar scheme can be achieved for coronagraphic occulters, where the PSF changes as the source position moves with respect to the mask.\n\nJWST's thermal evolution (e.g., changing the angle of the sunshield after slewing to a new target) causes small but significant distortions to the telescope backplane. WebbPSF has tools to modify OPDs, but high-fidelity simulations take time to calculate. Since the change to the PSF coefficients varies smoothly with respect to WFE drift components, it's simple to parameterize the coefficient residuals in a fashion similar to the field-dependence.\n\n## `webbpsf_ext` classes\n\nCurrently, only NIRCam and MIRI instrument classes are supported via the `NIRCam_ext` and `MIRI_ext` objects (although other instruments can be similarly implemented), which subclass the native `NIRCam` and `MIRI` objects found in WebbPSF. The key functions to call and generate PSF coefficients are:\n\n1. `gen_psf_coeff`: Creates a set of coefficients that will generate simulated PSFs for any arbitrary wavelength. This function first simulates a number of evenly- spaced PSFs throughout the specified bandpass (or the full channel). An nth-degree polynomial is then fit to each oversampled pixel using a linear-least squares fitting routine. The final set of coefficients for each pixel is returned as an image cube. The returned set of coefficient are then used to produce PSF via `calc_psf_from_coeff`. Useful for quickly generated imaging and dispersed PSFs for multiple spectral types.\n1. `gen_wfedrift_coeff`: This function finds a relationship between PSF coefficients in the presence of WFE drift. For a series of WFE drift values, we generate corresponding PSF coefficients and fit a polynomial relationship to the residual values. This allows us to quickly modify a nominal set of PSF image coefficients to generate a new PSF where the WFE has drifted by some amplitude.\n1. `gen_wfefield_coeff`: Science instruments generally have field-dependent wavefront errors, which have been carefully measured in ground-based cryovac test campaigns ([SI WFE](https://webbpsf.readthedocs.io/en/latest/jwst.html#si-wfe)). These aberrations are expected to be static throughout the JWST mission lifetime. Similar to the above function, we generate PSF coefficients at each of the sampled positions and create a `RegularGridInterpolator` function to quickly determine new coefficient residuals at arbitrary locations.\n1. `gen_wfemask_coeff`: For coronagraphic masks, slight changes in the PSF location relative to the image plane mask can substantially alter the PSF speckle pattern. This function generates a number of PSF coefficients at a variety of positions, then fits polynomials to the residuals to track how the PSF changes across the mask's field of view. Special care is taken near the 10-20mas region in order to provide accurate sampling of the SGD offsets.\n\n## Installing with pip\n\nDownload via pip:\n\n```bash\npip install webbpsf_ext\n```\n\n## Installing from source\n\nTo get the most up to date version of `webbpsf_ext`, install directly from the GitHub source.\n\nIn this case, you will need to clone the git repository:\n\n```bash\ngit clone https://github.com/JarronL/webbpsf_ext\n```\n\nThen install the package with:\n\n```bash\ncd webbpsf_ext\npip install .\n```\n\nFor development purposes, you can use editable installations:\n\n```bash\ncd webbpsf_ext\npip install -e .\n```\n\nThis is useful for helping to develop the code, creating bug reports, switching between branches and submitting pull requests to GitHub. Since the code then lives in your local GitHub directory, this method makes it simple to pull the latest updates straight from the GitHub repo, which are then immediately available to python at runtime without needing to reinstall.\n\n## Create Data Directory\n\nYou can define the directory that stores the PSF coefficients by setting the environment variable `WEBBPSF_EXT_PATH` to point to some data directory. All PSF coefficients will be saved here as they are generated to be reused later. For example, in `.bashrc` shell file, add:\n\n```bash\nexport WEBBPSF_EXT_PATH='$HOME/data/webbpsf_ext_data/'\n```\n\nIf this is not set, then a `psf_coeff` sub-directory is created in the already existing `WEBBPSF_PATH` directory.\n\n## Synphot Data Directory\n\nIf you have not already done so, you will need to provide a data files for the required `synphot` and `stsynphot` packages . These are used to generate the monochromatic PSFs and to calculate the throughput of the instrument. Data files for Synphot are distributed through the\n[Calibration Reference Data System](https://www.stsci.edu/hst/instrumentation/reference-data-for-calibration-and-tools). They are expected to follow a certain directory structure under the root directory, identified by the ``PYSYN_CDBS`` environment variable that *must* be\nset prior to using this package.\n\n1. Download [cdbs.tar.gz](https://arizona.box.com/shared/static/cbkxlwvokml7n1gref8nw3neg98kzcwn.gz) [approx. 900 MB] to obtain the full set of Synphot data files. Or download a minimum subset of files [here](https://arizona.box.com/shared/static/wgq7ymqsp8e7jfno8yk6o2igbnqlad8z.zip) [approx 50 MB].\n2. Untar into a directory of your choosing.\n3. Set the environment variable ``PYSYN_CDBS`` to point to that directory. For example, in .bashrc shell file, add:\n\n```bash\nexport PYSYN_CDBS='$HOME/data/cdbs/'\n```\n\nAfter re-sourcing your shell, you should now be able to successfully ``import synphot, stsynphot`` in a Python session.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "WebbPSF Extensions",
"version": "1.2.3",
"project_urls": {
"Homepage": "https://github.com/JarronL/webbpsf_ext"
},
"split_keywords": [
"jwst",
"psf",
"nircam",
"miri",
"simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "045b8972ca1ef700588f9b825cb273f0261f1667d3e3c96d922340ba9d151f54",
"md5": "e1961ffbad119c44fd343dd0681fbb96",
"sha256": "2eb73d8ff44f01187edabd5af99bb6c59900841559acd3467ae868e1f1f07c6c"
},
"downloads": -1,
"filename": "webbpsf_ext-1.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e1961ffbad119c44fd343dd0681fbb96",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8967822,
"upload_time": "2024-09-27T16:53:18",
"upload_time_iso_8601": "2024-09-27T16:53:18.879047Z",
"url": "https://files.pythonhosted.org/packages/04/5b/8972ca1ef700588f9b825cb273f0261f1667d3e3c96d922340ba9d151f54/webbpsf_ext-1.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5295fa74509cf11df5c2ff6670d292bdb1c6dcf211904987f9ee43562b5d3c39",
"md5": "3b1735677c72a291ef437bb51f3e041a",
"sha256": "8a854ff322164d2fc48b7c8b05d69b87caa40c4f79edc206f9d81620afbe88e4"
},
"downloads": -1,
"filename": "webbpsf_ext-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "3b1735677c72a291ef437bb51f3e041a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8496356,
"upload_time": "2024-09-27T16:53:24",
"upload_time_iso_8601": "2024-09-27T16:53:24.487707Z",
"url": "https://files.pythonhosted.org/packages/52/95/fa74509cf11df5c2ff6670d292bdb1c6dcf211904987f9ee43562b5d3c39/webbpsf_ext-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-27 16:53:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JarronL",
"github_project": "webbpsf_ext",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "webbpsf-ext"
}
JSON
