Development environment setup

Refl1D is a python package, and the most recent user interface is a web application.

Github account

We develop all code collaboratively using github, so if you don't have a github account already, please set one up at https://github.com/

For direct write access to the refl1d and bumps repositories, having having two-factor authentication enabled for your account is required.

ssh keys

If you don't already have an SSH key to use for github, follow the instructions here to create one and add it to your github account (ssh is pre-installed in recent Windows and MacOS systems)

Python environment

If you already have a recent Python installation that you are happy with, feel free to use that (python >=3.10).

Otherwise, the easiest way to get started is to install miniforge, which is an open version of the conda program which is also pre-configured to use the conda-forge repository. This repo is the most useful for open scientific application development.

miniforge install

You can get an installer for your system (MacOS, Windows or Linux) here: https://github.com/conda-forge/miniforge?tab=readme-ov-file#miniforge3

Run the installer, then from a terminal window (PowerShell or Terminal in Windows) run

conda init (then close and re-open your terminal)

environment creation

Create a new python environment for developing refl1d:

(you can leave off the git installation if you already have a system git installed)

conda create -c conda-forge -n refl1d python git

environment activation

conda activate refl1d

Getting bumps and refl1d sources

In a folder where you want to do your development, clone the repositories:

git clone [email protected]:bumps/bumps.git
git clone [email protected]:reflectometry/refl1d.git

installing bumps and refl1d packages in editable mode

In this mode, the packages are run directly from the source folders, so any changes made locally to the code have immediate effect.

Before running these commands, make sure the refl1d enviroment is activated in conda

pip install -e ./bumps
pip install -e ./refl1d

(it is important to use the ./ paths above because if you do pip install bumps it will install from pypi.org instead!)

installing the dependencies for running the webview server

pip install -r ./bumps/webview-requirements

Javascript environment (optional)

If you are going to work on the web interface (webview client), you will need to install javascript tools.

nodejs

This will also install the npm tool that we will use for building the client.

conda install nodejs

setup bumps-webview-client and refl1d-webview-client

cd $DEV_FOLDER/bumps/bumps/webview/client
npm install
npm link

cd $DEV_FOLDER/refl1d/refl1d/webview/client
npm install
npm link bumps-webview-client

(you can substitute the path to your development folder above, or define an environment variable)

It is important to install and link the bumps-webview-client package before running npm link bumps-webview-client in the refl1d client folder.

Building the client:

cd $DEV_FOLDER/refl1d/refl1d/webview/client
npm run build

Hot Module Replacement mode (if working on the client intensively)

In this mode, any changes to client code are immediately reflected in a connected running client

cd $DEV_FOLDER/refl1d/refl1d/webview/client
npm run dev

This starts the client and shows a link to connect to it (localhost:5173 or similar).

Next, start the python webview server with

refl1d-webview --headless --port 8080

... and then you can add ?server=localhost:8080 to the link, e.g.

http://localhost:5173/?server=localhost:8080