Package: hypercat
HYPERCATHypercubes of (clumpy) AGN toriHypercat images at 2.2 (blue) and 30 micron (gold), and their composite.SynopsisHandle a hypercube of CLUMPY brightness maps and 2D projected dust
maps. Easy-to-use classes and functions are provided to interpolate
images in many dimensions (spanned by the model parameters), extract
monochromatic or multi-wavelength images, as well as rotate images,
zoom in and out, apply PSFs, extract interferometric signals, quantify
morphologies, etc.AuthorsRobert Nikutta<robert.nikutta@gmail.com>, Enrique Lopez-Rodriguez, Kohei IchikawaVersionVersion of this document: 2022-09-24Current version of the HYPERCAT package:License and AttributionHYPERCAT is open-source software and freely available athttps://github.com/rnikutta/hypercat/andhttps://pypi.org/project/hypercat/under a permissiveBSD 3-clause
license.In short, if you are using in your research any of the HYPERCAT
software or its components, and/or the HYPERCAT model data hypercubes,
and/or telescope pupil images, please cite these two papers:Nikutta, Lopez-Rodriguez, Ichikawa, Levenson, Packham, Hönig,
Alonso-Herrero, "Hypercubes of AGN Tori (Hypercat) -- I. Models and
Image Morphology", ApJ (2021, accepted)Nikutta, Lopez-Rodriguez, Ichikawa, Levenson, Packham, Hönig,
Alonso-Herrero, "Hypercubes of AGN Tori (Hypercat) -- II. Resolving
the torus with Extremely Large Telescopes", ApJ (2021, accepted)Minimal install instructionsIf you don't mind installing HYPERCAT and its dependencies into your
current environment (real or virtual), simply run:pip install hypercator, if you are installing over an older version:pip install hypercat --upgradeIf you prefer to install HYPERCAT into a fresh new environment without affecting your existing Python installation, you can create a new environment in various ways.If you are a user of conda / anaconda / miniconda / astroconda:We recommend to update the conda-installled packages first (but you also first try to install HYPERCAT without updating):conda update --allAfter that:conda create -n hypercat-env python=3.7.2
conda activate hypercat-env

pip install hypercat --upgradeIf you are a user of pyenv:pyenv install 3.7.2
. .venv/bin/activate

pip install hypercat --upgradeInstallation trouble-shootingtbwHYPERCAT / CLUMPY model images and 2D dust cloud mapsHypercat needs to access the hypercubes of Clumpy images and dust
maps. They can be downloaded as hdf5 files from the link given athttps://www.clumpy.org/images/(which currently isftp://ftp.tuc.noirlab.edu/pub/nikutta/hypercat/).We offer several model files, which only differ in the wavelength range they cover:File nameSize compressed / raw (GB)NwaveWavelengths (micron)hypercat_20200830_all.hdf5271 / 91325all of the belowhypercat_20200830_nir.hdf544 / 14641.2, 2.2, 3.5, 4.8hypercat_20200830_mir.hdf5120 / 402118.7, 9.3, 9.8, 10, 10.3, 10.6, 11.3, 11.6, 12, 12.5, 18.5hypercat_20200830_fir.hdf565 / 219631.5, 37.1, 53, 89, 154, 214hypercat_20200830_submm.hdf542 / 1464350, 460, 690, 945Download and unpackingFor example, the*_all.hdf5.gzfile contains the image hypercube at
all sampled wavelengths. This is the maximally compressed version of
the hdf5 file, which must be uncompressed on the user’s computer
system. To reduce the peak storage required on the target computer,
both steps can be executed in one go (all commands in a single line):lftp -e 'set net:timeout 10; cat /pub/nikutta/hypercat/hypercat_20200830_all.hdf5.gz; bye' ftp.tuc.noirlab.edu | gunzip >
hypercat_20200830_all.hdf5The programlftpmust be installed on the target system, and 913 GB
of space must be available on it (but only 271 GB of compressed data
will be downloaded).File validationOne should also download the checksums fileftp://ftp.tuc.noirlab.edu/pub/nikutta/hypercat/hypercat_20200830.md5and verify the hypercube file:# this can take 30 minutes even on a modern computer
md5sum --ignore-missing -c hypercat_20200830.md5
hypercat_20200830_all.hdf5: OK

# or on MacOS and BSD variants
md5 hypercat_20200830_all.hdf5

#... and compare the printed hash with the one in the .md5 filePointing HYPERCAT to a model fileThe software, and the example Jupyter notebooks (see below) will need
to be instructed about the location of the model file(s). This is very
easy to do upon loading the model file; the notebooks have several
examples on how to accomplish this, e.g.import hypercat as hc
fname = 'hypercat_20200830_all.hdf5' # use your local location to the HDF5 model file
cube = hc.ModelCube(fname,hypercube='imgdata')  # use 'imgdata' for brightness maps, and 'clddata' for 2D cloud mapsExample Jupyter notebooksSeveral Jupyter example notebooks demonstrate some of HYPERCAT's
functionality. The easiest way to obtain them is to clone the HYPERCAT
GitHub repository, and to run the notebooks from there. Cloning the
repository will also download all necessary supplemental files used in
some notebooks such as, e.g., the telescope pupil images and the dust
opacity curve:git clone https://github.com/rnikutta/hypercat.git  # clone the git repository
cd hypercat/examples/  # change to the directory with example notebooks
jupyter-lab ./&  # run the notebooks locally; JupyterLab must be installed01-hypercat-basics.ipynb:
Loading a model hypercube, generating model images, images at
multiple wavelengths, images at multiple values of other model
parameters, accessing cloud maps02-hypercat-astro.ipynb:
Adding physical units to images, world coordinate system, field of
view and pixel scale operations, image rotation / position angle,
saving to FITS files03-hypercat-singledish.ipynb:
Telescope pupil images (JWST, Keck, GMT, TMT, ELT), simulating
observations with single-dish telescopes, noisy observations,
Richardson-Lucy deconvolotuion, detector pixel scale, flux
preservation, observations at multiple wavelengths04-hypercat-morphology-intro.ipynb:
Introduction to morphological measurements (on 2D Gaussians), image
centroid, rotation, measuring size of emission features, elongation,
half-light radius, Gini coefficient05-hypercat-morphology-clumpy.ipynb:
Morphology of the HYPERCAT model images; morphological sizes,
elongation, centroid location; compare morphologies of of emission
and their underlying dust distributions; from 2D cloud maps to real
cloud numbers per LOS; photon escape probability along a LOSUser ManualWARNING -- the User Manual is still work-in-progress:For more detailed installation instructions and other usage examples,
please see the HYPERCAT User ManualUser Manual(in
addition to theexample Jupyter notebooks)ContributingBug fixes and feature contributions to HYPERCAT are welcome. Please
make a pull request against the 'master' branch.