Getting Started#

Prerequisites#

polar-bits is designed to operate in Linux with miniconda. The hkl package for crystallography calculations and pyepics for EPICS communication are installed via Conda because they depend on compiled C/Fortran libraries. The rest of the packages are installed with pip.

Installation#

export ENV_NAME=polar-bits
conda create -y -n $ENV_NAME python=3.11 hkl pyepics aps-dm-api
conda activate $ENV_NAME
pip install -e ".[dev]"

hklpy LD_LIBRARY_PATH#

After creating the environment, set the library path so hklpy can find its compiled dependencies:

conda env config vars set LD_LIBRARY_PATH="$HOME/.conda/envs/$ENV_NAME/lib:$LD_LIBRARY_PATH"

Documentation dependencies#

To build the documentation locally, install the doc extras:

pip install -e ".[doc]"

Starting polar-bits#

Startup scripts are provided in startup_scripts/:

  • bluesky-4idb

  • bluesky-4idg

  • bluesky-4idh

  • bluesky-core

Note that these assume that the environment name is “polar-bits”.

The “b”, “g”, and “h” scripts start the corresponding endstation support. The main difference in these is that it loads the station-specific database catalog, and it connects to the devices labeled “core” or the selected station in src/id4_common/configs/devices.yml.

The “core” startup will ask whether you want to connect all devices or none. See next section for more details on loading specific devices.

Note that all devices are always loaded, but not connected.

Data Analysis#

polartools is the companion Python package for loading, processing, and plotting data collected at POLAR. It provides routines for XAS/XMCD analysis, diffraction peak fitting, image processing, and general data utilities. polartools functions are available in the session namespace after startup.

Loading Devices#

In order to connect or reload a device you cna use the following utility functions:

# List all available devices
find_loadable_devices()

# Filter by label
find_loadable_devices(label="4idg")

# Connect a specific device
load_device("transfocator")

# Disconnect and remove from baseline
remove_device("transfocator")

# Reload all devices (useful after devices.yml changes)
reload_all_devices()
reload_all_devices(stations=["core", "4idh"])  # for a specific beamline