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

conda config --add channels conda-forge

Step 2: Set Channel Priority

conda config --set channel_priority strict

Step 3: Remove Default Channels

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:

nano ~/.condarc

Ensure the file contains the following:

channels:
  - conda-forge
channel_priority: strict

Save and exit (Ctrl+O, then Ctrl+X).

Verification

To confirm your configuration, run:

conda config --show channels

You should see only conda-forge listed.

Install gfortran

macOS:

brew install gcc

Linux:

sudo apt install gfortran

Install Git

macOS:

brew install git

Linux:

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:

mkdir -p /preferred/path/guibrushr
cd /preferred/path/guibrushr/
git clone https://www.ict.inaf.it/gitlab/guibrushr/guibrushr

Step 2: Create Conda Environment

conda create -n guibrushr_env python=3.10

If the command above fails, try:

conda create -n guibrushr_env python=3.10 --override-channels -c conda-forge

Step 3: Activate the Environment

conda activate guibrushr_env

Step 4: Install GUIBRUSHR

Navigate to the GUIBRUSHR folder and install in development mode:

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

nano ~/.petitradtrans/petitradtrans_config_file.ini

Step 2: Update the Paths

The default configuration will look like this:

[Default files]

[Paths]

prt_input_data_path = /home/<username>/petitRADTRANS/input_data
prt_outputs_path = /home/<username>/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:

[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

cd /preferred/path/guibrushr/GUIBRUSHR/GUIBRUSHR/Files/Configuration_Path/

Step 2: Create configuration.csv

Create a file named configuration.csv with the following structure:

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:

Element,Path
petitRadTrans_path,/home/francesco/petitRADTRANS/input_data/
path_target_folders,/home/francesco/Target_GUIBRUSHR/

Field Descriptions

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:

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:

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:

# 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:

conda activate guibrushr_env

Launch GUIBRUSHR

Navigate to the GUIBRUSHR directory and start the application:

cd /preferred/path/guibrushr/GUIBRUSHR
python Start_GUIBRUSHR.py

Troubleshooting

Common Issues

Environment activation error:

# Make sure you created the environment with the correct name
conda env list

Import errors after installation:

# 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