creates basic docs

docs/configuration.rst

@@ -0,0 +1,74 @@
+.. _config:
+
+Configuration
+==============
+
+Each run of `unfold` requires a configuration file in the `TOML format <https://toml.io/en/>`. The configuration file
+is divided into sections:
+
+- **paths**: provides the input file paths.
+- **output**: describes the properties of the output.
+- **inversion**: defines inversion parameters, how the inversion operation is defined.
+- **model**: defines the parameters for the ``sklearn`` ElasticNet that is used.
+- **execution**: describes the execution of the inversion, including computer specific properties like the number of threads.
+
+.. note::
+    All sections and parameters are expected in the configuration file. There are no optional parameters with defaults.
+
+`We provide an example configuration file here. <https://github.com/ECCCO-mission/overlappogram/blob/main/example_config.toml>`
+
+**paths** section
+------------------
+
+There are four configurables for this section:
+
+- *overlappogram*: path to the overlappogram image to be inverted.
+- *weights*: path to the accompanying weights used in the inversion.
+- *response*: path to the instrument response.
+- *gnt*: path to the file containing atomic physics values from Chianti, the *G(n, t)* function.
+
+**output** section
+--------------------
+
+There are three configurables for this section:
+
+- *make_spectral*: if true, makes spectrally pure images as output. otherwise, these files are not made.
+- *directory*: path to the directory where output files are written.
+- *overwrite*: if true, output files will be overwritten. otherwise, the program will fail writing if a file already exists.
+
+**inversion** section
+----------------------
+
+There are six configurables for this section:
+
+- *solution_fov_width*: an integer for the field-of-view width in pixels used in the solution. We suggest 2.
+- *detector_row_range*: a list of two integers defining the range of detector rows to invert. For example, [10, 35] would run between 10 and 35.
+- *field_angle_range*: a list of two integers defining the range of field angles to use in inversion. Units are arc seconds.
+- *response_dependency_name*: for now, only "logt" is supported.
+- *response_dependency_list*: a list of floats defining the logarithm of the temperature used in the response dependency.
+- *smooth_over*: ?
+
+**model** section
+-------------------
+
+This section defines the parameters used by `Scikit-Learn's ElasticNet <https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.ElasticNet.html>`.
+You can find more exhaustive descriptions of the parameters at that link in the `sklearn` documentation.
+
+There are six configurables for this section:
+
+- *alphas*: A list of floating point numbers defining the various values of alpha to iterate over. Alpha is a constant in ``sklearn`` that multiplies a penalty term.
+- *rhos*: A list of floating point numbers defining the various values of rho to iterate over. This corresponds to ``sklearn``'s `l1_ratio` parameter.
+- *warm_start*: Boolean indicating whether a warm start should be used when training the model. Note that if the *mode* (see the **execution** section) is "row" this has no effect.
+- *tol*: The tolerance for the optimization.
+- *max_iter*: The maximum number of iterations.
+- *selection*: Either set to "cyclic" or "random". If set to "random", a random coefficient is updated every iteration rather than looping over features sequentially by default.
+
+
+**execution** section
+-----------------------
+
+There are three configurables for this section:
+
+- *num_threads*: The number of threads to use when optimizing.
+- *mode_switch_thread_count*: Only used if *mode* is set to "hybrid". In that case, when the number of remaining threads is less than this value, the optimization switches from "chunked" to "row".
+- *mode*: The optimization mode can be set to three different values: "row", "chunked", or "hybrid". See :ref:`modes` for a description of what these do.

docs/development.rst

@@ -0,0 +1,28 @@
+Development
+============
+We encourage all contributions. Please see our `contribution guide first <https://github.com/eccco-mission/eccco-mission/blob/main/contributing.md>`_.
+
+We recommend working in a virtual environment.
+This can be created by running ``python -m venv venv``. Then, activate the environment with ``source venv/bin/activate``.
+You can then install the required packages with ``pip install -e ".[dev]"``.
+
+If at any time you run into issues, please contact us by :doc:`following the guidelines here <help>`.
+
+Setting up pre-commit
+----------------------
+
+The first time you develop code, you'll need to install the pre-commit. This checks that our style is consistent.
+It gets installed when you do ``pip install -r ".[dev]"`` but then requires you to activate them by
+running ``pre-commit install``. Now every time you commit, our checks will run first.
+
+Building the docs
+------------------
+The docs are built using ``sphinx``. First, you must install it and the other documentation requirements with ::
+
+    pip install -r ".[docs]"
+
+Then, navigate to the ``docs`` directory and run ``make html`` to build the docs.
+
+Running tests
+-------------
+To run the tests for this package, run ``pytest`` in the repository base directory.

docs/examples.rst

@@ -0,0 +1,4 @@
+Examples
+==========
+
+Coming soon!

docs/help.rst

@@ -0,0 +1,11 @@
+Help
+==============
+
+First of all, thank you for your support and use of the package!
+
+If you notice a bug, please `open an issue on GitHub <https://github.com/eccco-mission/overlappogram/issues/new>`_.
+
+If you need help using this code, please `start a discussion on GitHub <https://github.com/eccco-mission/overlappogram/discussions/new/choose>`_.
+We encourage using GitHub rather than email so that others can benefit from your inquiry too. We want to make this code
+as user-friendly as possible. If you're encountering an issue, it's likely someone else is too; you can help
+everyone by speaking up.

docs/index.rst

@@ -3,12 +3,19 @@
 Welcome to overlappogram's documentation!
 =========================================
 
-Coming soon!
+Overlappogram is a Python package for inverting overlappogram observations
+of the Sun, for examples MaGIXS, CubIXSS, or ECCCO observations.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   overview
+   configuration
+   examples
+   help
+   development
+
 
 
 Indices and tables

docs/overview.rst

@@ -0,0 +1,63 @@
+.. _overview:
+
+Overview
+=========
+
+.. image:: _static/overlappogram.png
+  :width: 800
+  :alt: overlappogram image
+
+``overlappogram`` works by accepting an overlappogram (an image of the Sun captured by a slitless spectrogram)
+and the corresponding response
+matrix for the instrument. It then utilizes row-by-row linear regression using an ElasticNet
+to recover an emission measure cube that could have created the observation. To verify
+this emission measure, it then generates spectrally pure maps which can be validated with a
+ground truth observation.
+
+Installation
+-------------
+
+``pip install overlappogram``
+
+
+Running
+--------
+
+The most direct way to run ``overlappogram`` is using the ``unfold`` terminal program that gets installed.
+It is executed simply: ``unfold config.toml`` where ``config.toml`` is a configuration file
+defined according to :ref:`config` documentation.
+
+
+.. _modes:
+
+Optimization modes
+--------------------
+
+There are three possible optimization modes: "row,", "chunked," and "hybrid."
+
+"row" is the simplest optimization mode and is recommended for newcomers. In this optimization mode, the overlappogram
+is divided into rows. Each row gets its own ElasticNet model to use when carrying out the inversion. Thus, each row is
+inverted independently.
+
+"chunked" is the next simplest optimization row. The image is divided into a number of *chunks*
+or sets of contiguous, non-overlapping rows.
+The number of chunks is set by the *num_threads* parameter in the **execution** section of the configuration file.
+Each chunk is given one ElasticNet model and a single thread for optimization. Thus, a single ElasticNet is used for
+multiple rows of the inversion. This allows us to use warm starting. Warm starting is when the previous row's solution
+is used as a starting point for inverting the next row in a chunk. To turn this feature on, set the *warm_start*
+parameter in the **model** section of the configuration to true when used the "chunked" mode.
+
+.. warning::
+    Sometimes the chunked mode will result in *chunk artifacts* in the resulting inversions.
+    These appear as discontinuous boundaries in the output spectrally pure images.
+    We do not yet understand when this happens and doesn't happen.
+    Thus, it is recommended to avoid chunked optimization unless you are confident.
+
+"hybrid" is a combination of the "chunked" and "row" optimization modes. The optimization begins in chunked mode but
+switches to the row mode to optimize CPU performance. When inverting an overlappogram, some rows are harder to invert
+than others and thus take more time. These rows tend to be adjacent and thus in the same chunk. Consequently, we noticed
+that when using the chunked mode, we would finish most of the chunks but be waiting on a few rows of a chunk to complete.
+Because chunks are done sequentially, there may only be a few rows left to invert.
+Thus, the "hybrid" mode will stop doing chunked inversion and instead use row-based inversion when fewer than a set number
+of rows remain to invert.
+This number is defined in the "mode_switch_thread_count" parameter of the **execution** section of the configuration file.

example_config.toml

@@ -5,7 +5,6 @@ response = "data/ECCCO_speedtest_runs/D27Feb2024_eccco_response_feldman_m_el_wit
 gnt = "data/ECCCO_speedtest_runs/master_gnt_eccco_inphotons_cm3persperpix_with_tables.fits"
 
 [output]
-prefix = "example"
 make_spectral = true
 directory = "output/example/"
 overwrite = true