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 can 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("crl")

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

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

For the CRL specifically there are two convenience shortcuts that sit on top of load_device("crl"):

crl_setup("h")          # switch the CRL sample-position offset to 4IDH
                        # (or "g"; pass nothing for an interactive prompt)
crl_size(50)            # set the focal size to 50 µm
                        # (< 5 µm triggers crl.minimize_button instead)
mov crl.beamsize 10     # write 10 µm directly to the focalSize PV
                        # (no setpoint <-> readback convergence wait)

Restarting a Session#

For a session restart inside an experiment that has already been set up once, the package ships a one-line helper that runs experiment_resume() then restore_session_state() and prints a per-knob status:

import id4_common.macros.startup_common  # noqa: F401

restore_session_state re-applies every auto-saved setup knob (PR setup, energy tracking, undulator offsets, counters, qxscan parameters) from RE.md["session_state"]. See Writing Macros for the full restart template and details on the per-experiment knobs that auto-save.