Installing Project Chameleon

Quick Start with Miniconda3

We recommend using Miniconda3 for the simplest installation. Miniconda3 installers can be downloaded from the Miniconda website, and installation instructions are available here. This method should be the easiest to get running for most users as it only requires a conda environment. If you are looking for a containerized version of Project Chameleon, instructions for installing and starting the Docker Image version can be found below.

Installation and Requirements

  1. Download the GitHub Repository

    Clone or download the GitHub repository somewhere accessible on your system. This can either be done by downloading a zip directly from the Github webpage, or through Github desktop. Both of these methods should function the same.

  2. Create a New Virtual Environment and Install Dependencies

    While any virtual environment manager should work, the example below uses Conda. The Python version must be 3.12.2 or newer. The commands below will both create a new virtual environment and install dependencies:

    conda env create -f environment.yml
conda activate project-chameleon

    Note that the environment.yml file will automatically name the new envrionment “project-chameleon”. To change this, edit the name in the environment.yml file and adjust the conda commands accordingly.

  3. ARPES Dependencies Installation (Optional) If you do not plan on using the ARPES function in Project Chameleon this step in installation is not necessary. The ARPES functions require the installation of one additional package called HTMDEC Formats. To install this package, the GitHub repository should be cloned or downloaded. Then, within the newly created conda environment, enter the htmdec_formats repository and run:

    pip install -e .

    After this package is installed, ARPES functions should work normally.

In case of trouble with installation, more detailed instructions on installation for some packages can be found on the.:doc:instructions and specifications <instructions_and_specifications> page. This page also details some processes and expected structures of Project Chameleon.

Running in Jupyter Notebooks

Jupyter notebooks are recommended for quick access to Project Chameleon functions.

To use:

  1. Install Jupyter Notebooks in your conda environment

    pip install notebook

  2. Open a Jupyter notebook.

    jupyter notebook

  3. In a new cell, add:

    from project_chameleon.rheedconverter import rheedconverter
rheedconverter('example.img', 'example.png')

This example uses the rheedconverter function, which takes two parameters: a .img input file and a .png ouput file. It is one of the simplest functions that can be used to test that the package is working.

Test files can be found in the tests/data/rheed folder of the repository. The files that can are included in the package and can be used for testing are Image107.img, rheed_test_image.img, and test.img. When the function is run, an ouput should be created with the name given to the output file. In the example above, the ouput would be named example.png. A full list of functions and usage examples is provided in the Data Types section.

Docker Image

Another way to deploy Project Chameleon is to use the public Docker image. This method does require that the user is familiar with Docker, but also does all of the installing of packages for you.

The image is built on the python:3.12-slim (Debian Linux) base image and contains a complete installation of Project Chameleon. Running the Docker image as-is will drop you into a bash terminal as the user (who has sudo privileges) in their home directory. More information on the Docker image can be found here.

If you prefer to install Project Chameleon directly on your system instead of using a Docker container, we recommend starting with a minimal installation of Conda, the open source package and environment management system.

Dependencies and Further Information

Full list of dependencies used by Project Chameleon:

Note on xylib Installation:

If you need help installing xylib, see the following files in the repository:

These provide additional platform-specific installation instructions.