Metadata-Version: 2.4
Name: quest_qso
Version: 1.0
Summary: A machine learning model to generate quasar spectra
Project-URL: Homepage, https://github.com/cosmic-dawn-group/QUEST
Project-URL: Bug Tracker, https://github.com/cosmic-dawn-group/QUEST/issues
Author-email: Francesco Guarneri <francesco.guarneri@uni-hamburg.de>, Jan-Torge Schindler <jan-torge.schindler@uni-hamburg.de>
License: BSD 3-Clause License
        
        Copyright (c) 2025, cosmic-dawn-group
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: astronomy,python,quasar,science,spectroscopy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.13,>=3.12
Requires-Dist: astropy>=6.1.6
Requires-Dist: atelier>=0.1
Requires-Dist: corner>=2.2.3
Requires-Dist: csaps>=1.2.0
Requires-Dist: cuda-selector>=0.1.5
Requires-Dist: dustmaps>=1.0.13
Requires-Dist: emcee>=3.1.6
Requires-Dist: gdown>=5.2.0
Requires-Dist: gmm-mi>=0.8.2
Requires-Dist: h5py>=3.12.1
Requires-Dist: jupyterlab>=4.3.0
Requires-Dist: matplotlib>=3.9.2
Requires-Dist: numba-extinction>=0.1.2
Requires-Dist: numba>=0.60.0
Requires-Dist: numpy>=2.0.2
Requires-Dist: pandas>=2.2.3
Requires-Dist: scikit-learn>=1.5.2
Requires-Dist: scipy>=1.14.1
Requires-Dist: speclite>=0.20
Requires-Dist: spectres>=2.2.2
Requires-Dist: tables>=3.10.1
Requires-Dist: torch>=2.5.1
Requires-Dist: torchvision>=0.20.1
Requires-Dist: tqdm>=4.67.0
Requires-Dist: umap-learn>=0.5.7
Description-Content-Type: text/markdown

# QUEST: A machine learning framework to generate quasar spectra

QUEST is an implementation of a Variational Auto-Encoder (VAE) with the primary purpose of generating realistic quasar spectra and post-processing them to obtain synthetic quasar photometry. QUEST can also be used to reconstruct spectra with limited wavelength coverage, absorption systems, and even the continuum blueward of the Lyman-$\alpha$ emission line (with some caveats).

Check out the [paper]() for a full breakdown of its capabilities and limitations.

## Install instructions

We recommend installing QUEST in a dedicated virtual environment.

1.  **Create and activate a virtual environment** (e.g., using `venv`):
    ```bash
    python -m venv venv_name
    source venv_name/bin/activate  # Linux/macOS
    ```

2.  **Install from source:**
    ```bash
    git clone [https://github.com/cosmic-dawn-group/QUEST.git](https://github.com/cosmic-dawn-group/QUEST.git)
    cd QUEST
    pip install -e .
    ```

3.  or **Install from PyPI:**
    ```bash
    pip install QUEST
    ```
    *Note: Updates on the PyPI version might lag slightly behind the main repository.*

    **A note of caution:** QUEST has been tested as much as possible, but there are surely bugs and aspects to improve. Please report any issue you find using the **GitHub Issues** tab, or consider sending us an email ([francesco.guarneri@uni-hamburg.de](mailto:francesco.guarneri@uni-hamburg.de)).

## Environment variables

QUEST uses a few environment variables to set its output folders and ensure that it does not overuse resources on shared machines.

* `QUEST_LOCALPATH` — General cache directory. This is the primary folder used to download all cached files and save generated spectra/photometry in the examples. If downloaded using the utilities included in QUEST, this will also contain the datasets used to train the model.
* `QUEST_LOG_TO_FILE` - QUEST logs to the terminal by default. However, if this variable is set to `True` or `1`, an additional log file will be created in `QUEST_LOCALPATH`.
* `AM_I_ON_SHARED_SERVER` - If set to `True` or `1`, QUEST will limit its resource usage (see details in `__init__.py` -- make sure to customize this to your needs!).
* `TORCH_SEED` - Sets the overall seed for `PyTorch`. If this is not set, the seed defaults to `42`. If negative, no seed is set. Otherwise, the seed will be set to the value of this variable.
* `TORCH_DEBUG` - Effectively sets `torch.autograd.set_detect_anomaly(True)`. This should only be used to debug issues with the model, as it greatly slows down any PyTorch operation.

Environment variables can be set (for example, in `bash`) using the `export` command:

```bash
export QUEST_LOCALPATH="/path/to/your/cache/folder"
```

Usage
-----
Head over to the `examples` folder, where we've included Jupyter notebooks showing how to load the model for inference, sample from it, or generate synthetic photometry.

Contributing
------------
Contributions are more than welcome! Please open an issue to report problems, open PRs to contribute to the code, or just let us know if you have any feature requests! We are a small team but are happy to receive feedback!

License
-------
See `LICENSE` in the repository root.