Write a lot of documentation (with some small code fixes)

changes/133.docs.rst

@@ -0,0 +1 @@
+Add a lot of docs, make a few small code fixes so the examples actually work.

docs/conf.py

@@ -119,6 +119,8 @@
     'logo_text_align': "left",
     'description': "Software developed by the Roman SNPIT",
     'sidebar_width':'250px',
+    'page_width':'75%',
+    'body_max_width':'120ex',
     'show_relbars':True,
 }
 

docs/development.rst

@@ -4,15 +4,157 @@
 Development
 ===========
 
+.. contents::
+
+
 If you're one of the phrosty developers, or are otherwise interested in contributing, here is some useful information.
 
+Note that fully running phrosty requires an NVIDIA GPU with enough memory.  Empirically, as 12GB GPU is not enough.  We have succesfully run phrosty on NVIDIA GPUs with 40GB of memory.
+
+.. _running-tests:
 
 Running Tests
 -------------
 
+**Warning**: all docker images are currently built only for the ``amd64`` architecture (also sometimes known as ``x86_64``).  If you're on ``arm64``, then things may not work, and if they do work, they may be horribly slow as you're emulating a different architecture.  NERSC's Perlmutter cluster, and any Linux system running on hardware with an Intel or AMD CPU, are on the ``amd64`` architecture.  Current Macs, and any other systems based on an ARM chip, are on the ``arm64`` architecture.
+
 Running all of the tests requires an NVIDIA GPU with enough memory.  We are able to run them on 40GB NVIDIA GPUs, a GPU with only 12GB is not enough.  (TODO: figure out the actual cutoff.)
 
-To run the tests, make sure to run the SNPIT container as described in :ref:`running-snpit-container`.  Inside the container, cd into the `/phrosty/phrosty/tests` directory and run::
+To run  the tests, forst make sure you've set up your environment and pulled down the necessary docker images as described in :ref:`phrosty installation prerequisites<phrosty-installation-prerequisites>`.  
+
+If you haven't already, get a copy of phrosty::
+
+  git clone https://github.com/Roman-Supernova-PIT/phrosty.git
+
+Second, in the same directory, get a copy of the photometry test datay::
+
+  git clone https://github.com/Roman-Supernova-PIT/photometry_test_data.git
+
+Make a couple of necessary directories::
+
+  mkdir dia_out_dir
+  mkdir phrosty_temp
+  
+Run the container with::
+
+  docker run --gpus=all -it \
+    --mount type=bind,source=$PWD,target=/home \
+    --mount type=bind,source=$PWD/photometry_test_data,target=/photometry_test_data \
+    --mount type=bind,source=$PWD/dia_out_dir,target=/dia_out_dir \
+    --mount type=bind,source=$PWD/phrosty_temp,target=/phrosty_temp \
+    --env LD_LIBRARY_PATH=/usr/lib64:/usr/lib/x86_64-linux-gnu:/usr/local/cuda/lib64:/usr/local/cuda/lib64/stubs \
+    --env PYTHONPATH=/roman_imsim \
+    --env OPENBLAS_NUM_THREADS=1 \
+    --env MKL_NUM_THREADS=1 \
+    --env NUMEXPR_NUM_THREADS=1 \
+    --env OMP_NUM_THREADS=1 \
+    --env VECLIB_MAXIMUM_THREADS=1 \
+    --env TERM=xterm \
+    rknop/roman-snpit-env:cuda-dev \
+    /bin/bash
+
+**On NERSC Perlmutter**, run the container with::
+
+  podman-hpc run --gpu -it \
+    --mount type=bind,source=$PWD,target=/home \
+    --mount type=bind,source=$PWD/photometry_test_data,target=/photometry_test_data \
+    --mount type=bind,source=$PWD/dia_out_dir,target=/dia_out_dir \
+    --mount type=bind,source=$PWD/phrosty_temp,target=/phrosty_temp \
+    --env LD_LIBRARY_PATH=/usr/lib64:/usr/lib/x86_64-linux-gnu:/usr/local/cuda/lib64:/usr/local/cuda/lib64/stubs \
+    --env PYTHONPATH=/roman_imsim \
+    --env OPENBLAS_NUM_THREADS=1 \
+    --env MKL_NUM_THREADS=1 \
+    --env NUMEXPR_NUM_THREADS=1 \
+    --env OMP_NUM_THREADS=1 \
+    --env VECLIB_MAXIMUM_THREADS=1 \
+    --env TERM=xterm \
+    --annotation run.oci.keep_original_groups=1 \
+    registry.nersc.gov/m4385/rknop/roman-snpit-env:cuda-dev \
+    /bin/bash
+
+Once inside the container, cd into ``/home/phrosty/phrosty/tests`` and run::
 
   SNPIT_CONFIG=phrosty_test_config.yaml pytest -v
 
+
+Manually running a test lightcurve
+------------------------------------
+
+Currently, we do not have tests written for ``phrosty/pipeline.py``; this will be rectified soon, and hopefully this documentation will be updated to reflect that.
+
+If you want to build a lightcurve using the test data, follow the instructions in the previous section for getting the ``phrosty`` and ``photometry_test_data`` archives, and for pulling the ``cuda-dev`` version of the roman SNPIT docker image.
+
+You need a few of extra directories when running your container, to store temporary and output data.  You can put these where you want, but for this example we are going to assume you make three directories underneath the same place you checked out the two git archvies: ``phrosty_temp``, ``dia_out_dir``, and ``lc_out_dir``.
+
+With these directories in place, run a container with::
+
+  docker run --gpus=all -it \
+    --mount type=bind,source=$PWD,target=/home \
+    --mount type=bind,source=$PWD/photometry_test_data,target=/photometry_test_data \
+    --mount type=bind,source=$PWD/phrosty_temp,target=/phrosty_temp \
+    --mount type=bind,source=$PWD/dia_out_dir,target=/dia_out_dir \
+    --mount type=bind,source=$PWD/lc_out_dir,target=/lc_out_dir \
+    --env LD_LIBRARY_PATH=/usr/lib64:/usr/lib/x86_64-linux-gnu:/usr/local/cuda/lib64:/usr/local/cuda/lib64/stubs \
+    --env PYTHONPATH=/roman_imsim \
+    --env OPENBLAS_NUM_THREADS=1 \
+    --env MKL_NUM_THREADS=1 \
+    --env NUMEXPR_NUM_THREADS=1 \
+    --env OMP_NUM_THREADS=1 \
+    --env VECLIB_MAXIMUM_THREADS=1 \
+    --env TERM=xterm \
+    rknop/roman-snpit-env:cuda-dev \
+    /bin/bash
+
+**on NERSC Perlmutter**, the command would be::
+
+  podman-hpc run -gpu -it \
+    --mount type=bind,source=$PWD,target=/home \
+    --mount type=bind,source=$PWD/photometry_test_data,target=/photometry_test_data \
+    --mount type=bind,source=$PWD/phrosty_temp,target=/phrosty_temp \
+    --mount type=bind,source=$PWD/dia_out_dir,target=/dia_out_dir \
+    --mount type=bind,source=$PWD/lc_out_dir,target=/lc_out_dir \
+    --env LD_LIBRARY_PATH=/usr/lib64:/usr/lib/x86_64-linux-gnu:/usr/local/cuda/lib64:/usr/local/cuda/lib64/stubs \
+    --env PYTHONPATH=/roman_imsim \
+    --env OPENBLAS_NUM_THREADS=1 \
+    --env MKL_NUM_THREADS=1 \
+    --env NUMEXPR_NUM_THREADS=1 \
+    --env OMP_NUM_THREADS=1 \
+    --env VECLIB_MAXIMUM_THREADS=1 \
+    --env TERM=xterm \
+    --annotation run.oci.keep_original_groups=1 \
+    registry.nersc.gov/m4385/rknop/roman-snpit-env:cuda-dev \
+    /bin/bash
+
+If you placed any of the new directories anywhere other than underneath your current working directory, modify the ``source=...`` parts of the command above to reflect that.
+
+Inside the container, cd into ``/home/phrosty`` and try running::
+
+  nvidia-smi
+
+If you don't get errors, it should list the nvidia GPUs you have available.  If it doesn't list GPUs, then the rest of this won't work.
+
+Next, try running::
+
+  cd /home/phrosty
+  pip install -e .
+  SNPIT_CONFIG=phrosty/tests/phrosty_test_config.yaml python phrosty/pipeline.py --help | less
+
+You should see all the options you can pass to phrosty.  There are a lot, because there are (verbose) options for everything that's in the config file.  Press ``q`` to get out of ``less``.
+
+Try running::
+
+  SNPIT_CONFIG=phrosty/tests/phrosty_test_config.yaml python phrosty/pipeline.py \
+    --oid 20172782 \
+    --ra 7.551093401915147 \
+    --dec -44.80718106491529 \
+    -b Y106 \
+    -t phrosty/tests/20172782_instances_templates_1.csv \
+    -s phrosty/tests/20172782_instances_science_2.csv \
+    -p 3 -w 3 \
+    -v
+
+If all is well, after it's done running the output will end with something like::
+
+  [2025-08-13 17:35:24 - INFO] - Results saved to /lc_out_dir/data/20172782/20172782_Y106_all.csv
+
+On your host system (as well as inside the container), you should see new files in ``lc_out_dir``, ``dia_out_dir``, and ``phrosty_temp``.  (Inside the container, these are at ``/lc_out_dir``, ``/dia_out_dir``, and ``/phrosty_temp``.)

docs/index.rst

@@ -9,9 +9,29 @@ This is the documentation for phrosty.
 
 This package contains the Python software suite developed for use with the Roman Telescope project, as part of the Roman Supernova Project Implementation Team (PIT) project. 
 
-<<ENTER STATEMENT OF NEED HERE>>
+Statement of Need
+=================
 
-<<STATE OF THE FIELD>>
+Difference imaging analysis (DIA) is a technique in transient analysis that allows both transient detection and photometric measurements. Broadly, this method involves subtracting two images, one with a transient and a "reference" image without a transient, to isolate the object of interest. 
+
+The Nancy Grace Roman Space Telescope (_Roman_) is NASA’s first survey-oriented flagship mission. Its design is optimized for cosmological studies, which includes extraction and precision analysis of Type Ia Supernova (SN Ia) light curves. Analysis of these data pose several challenges: (1) the enormous quantity of data that will be returned on a regular basis, and (2) the spatially-dependent nature of the image properties as a function of location on the detector, which directly affects ease of (3) obtaining the required <1\% flux precision on SN Ia measurements.
+
+_Roman_ is expected to generate approximately 30 PB of data during its first five years of operation (16.5 TB per day). In comparison, NASA's Hubble Space Telescope has produced approximately 400 TB of data during its full 35 years of operation (31 GB per day). At 530 times the data rate of Hubble, BLAH BLAH FIGURE OUT WITH MEG WHAT NUMBERS TO SAY
+
+Other DIA and forced photometry survey pipelines are insufficient to process this quantity of data. For example, the Dark Energy Survey (DES) pipeline takes three hours to do DIA on a single image (parallelizable), with additional time for forced photometry [@destime]. 
+
+`phrosty` is a DIA and forced photometry pipeline that addresses these challenges. We integrate the saccadic fast fourier transform (`SFFT <https://ui.adsabs.harvard.edu/abs/2022ApJ...936..157H/abstract>`_) method for difference imaging analysis, which uses a flexible delta basis function that can accommodate Roman’s spatially-varying point spread function (PSF). `phrosty` uses both GPU and CPU computation; this architecture has been carefully chosen to address the challenge of processing the large quantity of survey data within a reasonable amount of time. 
+
+Because Roman software is currently under-development, there is no similar publicly available all-in-one pipeline that takes _Roman_ images as input and outputs light curves. The architecture choices made in development have substantially accelerated processing time such that `phrosty` is among the fastest astronomical DIA pipelines available.
+
+State of the Field
+===================
+
+TODO LAUREN
+
+
+Contact and Support
+===================
 
 Individuals who wish to contribute to phrosty, report issues, or seek support are encouraged to submit an issue via [GitHub](https://github.com/Roman-Supernova-PIT/phrosty/issues) and use the pre-loaded templates for feature requests and issue reports. Please include as much detail as possible, including a description of the problem, any associated error messages, inputs, and details about the environment the user is running. Please adhere to the phrosty [code of conduct](https://github.com/Roman-Supernova-PIT/phrosty/blob/main/CODE_OF_CONDUCT.md).