search

lucaskorol21 / GO-RXR

BSD 3-Clause "New" or "Revised" License
2 stars 1 forks source link

readme


Global Optimization of Resonant X-ray Reflectometry

A scientific tool for material scientists.

Key Features • Install/Configure • How-to-use • Credits • License • Publications

Key Features

Getting Started

Linux (Recommended Configuration)

Tested on 22.04

Installation

1. Clone GO-RXR from the main branch in this repository:

$ git clone https://github.com/lucaskorol21/GO-RXR.git

2. Prerequisites and Setup (Tested with Python 3.10.14)

2.0. Ensure Python 3.10 is Installed (Recommended Version)

Before setting up the virtual environment, make sure Python 3.10 is installed on your system:

  $ python3.10 --version

If Python 3.10 is installed, you should see an output like Python 3.10.x. If not, follow the steps below to install it.

2.1. Set Up the Virtual Environment

2.2. Install Package Dependencies

Install the required Python packages using pip:

  (venv-go-rxr) $ pip install .

This command will handle the installation of all dependencies, including compiling any Cython extensions.

Running the Application

Go back to the root of the repository and run the GUI: 

(venv-go-rxr) $ python GUI_GO.py

After running the GUI_GO.py file, the start screen will be displayed:

Start screen of GO-RXR. The interface is divided into three main sections: 1) Toolbar, 2) Workspace Navigator, and 3) Workspace Area. \label{fig:start-screen}

Windows (using WSL)

For Windows users, we recommend using Windows Subsystem for Linux (WSL) to run GO-RXR. WSL allows you to run a full Linux distribution alongside your Windows installation without the need for a virtual machine or dual-boot setup. This method provides a more consistent and reliable environment, especially for projects like GO-RXR that are designed to work seamlessly on Linux.

This configuration was tested on Windows 11 Home and Windows 11 Education.

Steps to Set Up and Run GO-RXR on Windows Using WSL

  1. Install WSL and Ubuntu

    • Open a PowerShell terminal as Administrator and run: 
      $ wsl --install
    • Recommended: install Ubuntu 22.04 or 24.04 if available.
    • Restart your computer after installation.
    • Open the Ubuntu application (available in the Start Menu), and follow the prompts to create a UNIX username and password.

  2. Update and Upgrade Ubuntu

    • Open the Ubuntu terminal and run: 
      $ sudo apt update && sudo apt full-upgrade -y

  3. Set Up Python Environment

    • Verify if Python 3.10 is installed: 

      $ python3 --version

      Recommended: Python 3.10.12 if available.

    • If Python 3.10 is not installed, you can install it as follows

      $ sudo apt install python3.10

  4. Clone the Repository

    • Git should already be installed, but you can install it with: 

      $ sudo apt install git -y

    • Clone the GO-RXR repository: 

      $ git clone https://github.com/lucaskorol21/GO-RXR.git

    • Navigate to the cloned directory: 

      $ cd GO-RXR/

  5. Set Up the Virtual Environment

    • Create the virtual environment using Python 3.10 (inside the GO-RXR directory): 

      $ python3.10 -m venv venv-go-rxr

    • Activate the virtual environment: 

      (venv-go-rxr) $ source venv-go-rxr/bin/activate

  6. Install Package Dependencies

    • Install the required Python packages using pip:

      (venv-go-rxr) $ pip install .

      This command will handle the installation of all dependencies, including compiling any Cython extensions.

  7. Running the Application

    • Go back to the root of the repository and run the GUI: 
      (venv-go-rxr) $ python GUI_GO.py

Advanced Installation Notes and Known Issues

This section provides additional details for less common configurations and troubleshooting.

Ubuntu 24.04

WSL on ARM64

For matplotlib, ensure that you have Pillow installed

(venv-go-rxr) $ pip install Pillow

Resolving PyQt5 Conflicts - Ubuntu.

If you encounter conflicts with the PyQt5 package during installation or usage, this discussion might be useful. Try the following steps:

# Install necessary dependencies
$ sudo apt-get install pyqt5-dev libqt5multimedia5-plugins -y

# Remove existing PyQt5 installations from the virtual environment
$ sudo rm -f -r /usr/lib/python3/dist-packages/PyQt5 /path/to/your/virtualenv/lib/python3.x/site-packages/PyQt5

# Create a symbolic link from the OS libraries to the virtual environment
$ sudo ln -f -s /usr/lib/python3/dist-packages/PyQt5 /path/to/your/virtualenv/lib/python3.x/site-packages/PyQt5

Replace /path/to/your/virtualenv with the path to your virtual environment directory and 3.x with the appropriate Python version (e.g., 3.10, 3.9, etc.). These commands aim to ensure that the global version of PyQt5 matches the one specified in your setup file by using the operating system's libraries and creating a symbolic link accordingly.

Resolving PyQt5 Conflicts - WSL.

If you encounter conflicts with the PyQt5 package during installation or usage (issues were noticed on Windows 11 Education) you might need to update the wsl version. Try the following steps:

  1. Update WSL:
    Open a new console and run:

    $ wsl --update

  2. Run the GUI:

    After updating WSL, return to the Ubuntu console and run:

    (venv-go-rxr) $ python GUI_GO.py

Testing

Automated Testing via GitHub Actions

The non-GUI tests are automatically run on every push and merge to the repository through GitHub Actions. This ensures that any new code changes do not introduce regressions or errors in the core functionality of the software.

Running Tests Locally

You can also run all tests locally using the test scripts provided in the TESTS folder. This includes both GUI and non-GUI tests.

1. Running All Tests

To run all tests at once, you can use the run_all_tests.py script in the TESTS directory:

(venv-go-rxr) $ python TESTS/run_all_tests.py

This script will execute all the test scripts in the TESTS folder.

2. Running Individual Tests

If you wish to run specific tests, you can directly execute the individual test scripts. For example:

Test Coverage

The tests cover the following components of the GO-RXR software:

Make sure to have the virtual environment activated and all dependencies installed before running the tests.

Documentation

The User Guide can be found in /DOCS. Also, the file Tutorial/Tutorial.pdf contains two detailed examples describing the step-by-step procedures to start using the GUI.

Credits

This software uses the following open source packages:

Contribution made by:

GO-RXR would have not been possible without the University of Saskatchewan and the funding provided by the U of S Physics and Engineering Physics Department, the NSERC-CREATE to INSPIRE fellowship, and the NSERC CGS M.

License

GO-RXR has been developed by the QMaX and Numerical Simulation Lab at the Department of Physics and Engineering Physics, University of Saskatchewan. The distribution of GO-RXR is subject to the terms and conditions of the BSD 3-Clause License. For specific details, please refer to the LICENSE file included with this distribution.

Contributing

We welcome contributions from the community! If you're interested in contributing to GO-RXR, please read our Contribution Guidelines for more information.

Publications

The GO-RXR software package has been utilized for analyzing the RXR data in the papers:

Bugs

If you encounter any issues, feel free to contact me at lsk601@usask.ca.