Installation ============ Prerequisites ------------- Before installing GUIBRUSHR, ensure you have the following installed on your system. Install Conda ~~~~~~~~~~~~~ If you don't already have Conda installed, download it from `conda.io `_. Removing Anaconda Default Channels ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To avoid potential licensing fees associated with Anaconda's default package channels, configure Conda to use the community-maintained ``conda-forge`` channel instead. **Step 1: Add conda-forge Channel** .. code-block:: bash conda config --add channels conda-forge **Step 2: Set Channel Priority** .. code-block:: bash conda config --set channel_priority strict **Step 3: Remove Default Channels** .. code-block:: bash conda config --remove channels defaults .. note:: If the command above returns an error, manually edit the configuration file instead. **Manual Configuration (if needed)** If Step 3 fails, edit the ``.condarc`` file directly: .. code-block:: bash nano ~/.condarc Ensure the file contains the following: .. code-block:: yaml channels: - conda-forge channel_priority: strict Save and exit (``Ctrl+O``, then ``Ctrl+X``). **Verification** To confirm your configuration, run: .. code-block:: bash conda config --show channels You should see only ``conda-forge`` listed. Install gfortran ~~~~~~~~~~~~~~~~~ **macOS:** .. code-block:: bash brew install gcc **Linux:** .. code-block:: bash sudo apt install gfortran Install Git ~~~~~~~~~~~~ **macOS:** .. code-block:: bash brew install git **Linux:** .. code-block:: bash sudo apt install git Installing GUIBRUSHR -------------------- .. important:: To access the GUIBRUSHR project, please email `paolo.giacobbe@inaf.it `_ or `francesco.amadori@inaf.it `_ to request an invitation to the GitLab group. Step 1: Clone the Repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Open a terminal and execute the following commands: .. code-block:: bash mkdir -p /preferred/path/guibrushr cd /preferred/path/guibrushr/ git clone https://www.ict.inaf.it/gitlab/guibrushr/guibrushr Step 2: Create Conda Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash conda create -n guibrushr_env python=3.10 If the command above fails, try: .. code-block:: bash conda create -n guibrushr_env python=3.10 --override-channels -c conda-forge Step 3: Activate the Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash conda activate guibrushr_env Step 4: Install GUIBRUSHR ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Navigate to the GUIBRUSHR folder and install in development mode: .. code-block:: bash cd /preferred/path/guibrushr/GUIBRUSHR pip install -e . pip install --upgrade "guibrushr[upgrade]" Configuration ------------- GUIBRUSHR requires two configuration steps: setting up petitRADTRANS and creating the GUIBRUSHR configuration file. Part 1: Setting up petitRADTRANS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GUIBRUSHR requires **petitRADTRANS** to be properly configured. Follow these official tutorials to set up the ``input_data`` folder and download molecular data at both high and low resolution: * `Getting Started with petitRADTRANS `_ * `High-Resolution Spectra Tutorial `_ Pre-flight Checklist ^^^^^^^^^^^^^^^^^^^^ Before running GUIBRUSHR, ensure you have completed the following: * Defined the location of your petitRADTRANS ``input_data`` folder * Downloaded at least one molecule of interest at both high and low resolution * Defined the location of your ``target`` folder Configure petitRADTRANS Paths ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. important:: After installing petitRADTRANS, you must configure the data paths. **Step 1: Open the Configuration File** .. code-block:: bash nano ~/.petitradtrans/petitradtrans_config_file.ini **Step 2: Update the Paths** The default configuration will look like this: .. code-block:: ini [Default files] [Paths] prt_input_data_path = /home//petitRADTRANS/input_data prt_outputs_path = /home//petitRADTRANS/outputs [URLs] prt_input_data_url = https://keeper.mpdl.mpg.de/d/ccf25082fda448c8a0d0/?p= Replace the default paths with your actual petitRADTRANS installation directory: .. code-block:: ini [Default files] [Paths] prt_input_data_path = /pRT/preferred/path/petitRADTRANS/input_data prt_outputs_path = /pRT/preferred/path/petitRADTRANS/outputs [URLs] prt_input_data_url = https://keeper.mpdl.mpg.de/d/ccf25082fda448c8a0d0/?p= Replace ``/pRT/preferred/path/petitRADTRANS`` with the absolute path to your petitRADTRANS installation. **Step 3: Save and Exit** Press ``Ctrl+O`` to save, then ``Ctrl+X`` to exit nano. Part 2: Creating the GUIBRUSHR Configuration File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Step 1: Navigate to Configuration Directory** .. code-block:: bash cd /preferred/path/guibrushr/GUIBRUSHR/GUIBRUSHR/Files/Configuration_Path/ **Step 2: Create** ``configuration.csv`` Create a file named ``configuration.csv`` with the following structure: .. code-block:: text Element,Path petitRadTrans_path,/pRT/preferred/path/petitRADTRANS/input_data/ path_target_folders,/target/preferred/path/ Configuration Example ^^^^^^^^^^^^^^^^^^^^^ Here's a complete example of the ``configuration.csv`` file: .. code-block:: text Element,Path petitRadTrans_path,/home/francesco/petitRADTRANS/input_data/ path_target_folders,/home/francesco/Target_GUIBRUSHR/ .. list-table:: Field Descriptions :header-rows: 1 :widths: 30 70 * - Field - Description * - ``petitRadTrans_path`` - Absolute path to your petitRADTRANS ``input_data`` folder * - ``path_target_folders`` - Absolute path to your GUIBRUSHR target data folder .. tip:: Always use absolute paths to avoid potential path resolution issues. Part 3: Git Configuration for Local Modifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``molecules.yaml`` configuration file is tracked in the repository but is meant to be customized locally. To prevent Git from tracking your local changes to this file: Step 1: Tell Git to Ignore Local Changes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After cloning the repository, run: .. code-block:: bash git update-index --assume-unchanged GUIBRUSHR/GUIBRUSHR/Files/Configuration_Yaml/molecules.yaml This tells Git to ignore any local modifications you make to ``molecules.yaml``, so your custom molecule configurations won't appear in ``git status`` or be accidentally committed. Step 2: Verify the Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To check which files are marked as assume-unchanged: .. code-block:: bash git ls-files -v | grep '^h' Files marked with ``h`` (instead of ``H``) are being ignored for local changes. Managing Updates from Remote ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the ``molecules.yaml`` file is updated in the remote repository and you want to pull those changes: .. code-block:: bash # Temporarily remove the ignore flag git update-index --no-assume-unchanged GUIBRUSHR/GUIBRUSHR/Files/Configuration_Yaml/molecules.yaml # Pull the latest changes git pull # Reapply the ignore flag git update-index --assume-unchanged GUIBRUSHR/GUIBRUSHR/Files/Configuration_Yaml/molecules.yaml .. note:: If you have local modifications when pulling remote updates, you may need to stash your changes first with ``git stash``, pull the updates, then reapply your changes with ``git stash pop``. Why This Approach? ^^^^^^^^^^^^^^^^^^ The ``molecules.yaml`` file contains default molecular species configurations that should be included when cloning the repository. However, each user may need to add or modify molecules based on their specific research needs. Using ``git update-index --assume-unchanged`` allows you to: * Keep the default configuration in the repository * Make local customizations without affecting version control * Avoid accidentally committing personal configuration changes * Still receive updates to the file from the main repository when needed Usage ----- Activate the Environment ~~~~~~~~~~~~~~~~~~~~~~~~~ Before using GUIBRUSHR, always activate the Conda environment: .. code-block:: bash conda activate guibrushr_env Launch GUIBRUSHR ~~~~~~~~~~~~~~~~~ Navigate to the GUIBRUSHR directory and start the application: .. code-block:: bash cd /preferred/path/guibrushr/GUIBRUSHR python Start_GUIBRUSHR.py Troubleshooting --------------- Common Issues ~~~~~~~~~~~~~~ **Environment activation error:** .. code-block:: bash # Make sure you created the environment with the correct name conda env list **Import errors after installation:** .. code-block:: bash # Reinstall in development mode pip install -e . --force-reinstall **Configuration file not found:** * Verify the ``configuration.csv`` file exists in the correct directory * Check that paths in the CSV file are absolute and correct **petitRADTRANS not found:** * Ensure petitRADTRANS is properly installed and configured * Verify the path in ``~/.petitradtrans/petitradtrans_config_file.ini`` is correct * Check that molecular data has been downloaded **Permission denied errors:** * Ensure you have write permissions for the output directories * Check that all paths in ``configuration.csv`` are accessible