CMS User Guide

Welcome to the CMS User Guide! This is a comprehensive resource for CMS information, operation, and data analysis.

Available Guides

This documentation includes:

  • Python Starter Guide: Step-by-step guide for setting up Python and Anaconda on Windows
  • runXS.py Starter Guide: Instructions for running and customizing the runXS.py script from SciAnalysis

Viewing this Documentation

Online

The documentation is automatically published to GitHub Pages whenever changes are pushed to the main branch.

Local Development

To build and view this documentation locally:

  1. Install mdbook:

    # On macOS
brew install mdbook

# On Linux
cargo install mdbook

# On Windows
# Download from https://github.com/rust-lang/mdBook/releases

  2. Build the book:

    mdbook build

  3. Serve locally with live reload:

    mdbook serve --open

The documentation will be available at http://localhost:3000.

Contributing

This guide is open to the public. Feel free to contribute improvements and additions!

How to Access Your Data via Globus

  1. Go to https://www.globus.org and click Login.
    Select Brookhaven National Laboratory as your institution and log in using your BNL credentials.

  2. Once logged in, open Collections (left menu) and search for NSLS2.
    Select the NSLS2 collection.

  3. In the NSLS2 collection, click File Manager.

  4. Change the default path (your home directory) to the CMS beamline data directory:

/nsls2/data/cms/proposals/2025-3/pass-xxxxxx/experiments/

  1. Browse to the folder corresponding to your run or experiment.

  2. For the second endpoint, choose your local machine or institution’s Globus endpoint.
    If you don’t have one, install Globus Connect Personal and then re-try.

  3. With both endpoints active, select the files or folders you want to transfer using the checkboxes, then click Transfer or Sync to….

Python Starter Guide

🧰 PART 1: Install Required Tools

1.

Install Anaconda (Python with Conda)

  1. Go to: https://www.anaconda.com/download/
  2. Download the Windows 64-bit version.
  3. Run the installer:
    • Choose “Just Me”
    • (Optional) Check the box: Add Anaconda to my PATH
    • Finish the installation.

2.

Install Visual Studio Code (VS Code)

  1. Go to: https://code.visualstudio.com/
  2. Download and install using the defaults.
  3. Check “Add to PATH” and “Register Code as editor” during install.

📦 PART 2: Download SciAnalysis

3.

Download ZIP from GitHub

  1. Visit: https://github.com/CFN-SoftBio/SciAnalysis
  2. Click the green “Code” button → Choose “Download ZIP”.
  3. Save the file to your Desktop.
  4. Right-click the ZIP file → Extract All.
  5. Rename the extracted folder to just SciAnalysis.

🧭 PART 3: Setup Environment Using Command Prompt

4.

Open Command Prompt

  • Press Windows + R, type cmd, press Enter.

5.

cd C:\Users\YourUsername\Desktop\SciAnalysis

To check, type:

dir

You should see files like setup.py.

6.

Create and Activate Conda Environment

conda create -n scianalysis_env python=3.9 -y

Then activate it:

conda activate scianalysis_env

7.

Install Required Packages (That may take long to figure out)

Install SciAnalysis dependencies:

conda install numpy

Or multiple package at once:

conda install scipy matplotlib h5py lxml pillow -y

📝 PART 4: Edit the Script in VS Code

8.

Open VS Code

  1. Launch VS Code.
  2. Go to File → Open Folder → Select: runWS.py

9.

Install Python Extension in VS Code

  1. Click the Extensions icon (left bar).
  2. Search “Python” and click Install.

10.

Edit the Script

  1. Open: runWS.py
  2. You can adjust input/output paths or settings as needed.

▶️ PART 5: Run the Script

Back in Command Prompt:

  1. Make sure you’re in the right folder:
cd C:\Users\YourUsername\YourDataFolder
conda activate scianalysis_env
  1. Run the WAXS analysis script:
python runWS.py

runXS.py Starter Guide

Here’s a step-by-step guide to running and customizing the runXS.py script from SciAnalysis on your own Windows machine:

✅ 1. Set the SciAnalysis Path

At the top of the script, you’ll see:

SciAnalysis_PATH='/home/kyager/current/code/SciAnalysis/main/'
SciAnalysis_PATH in sys.path or sys.path.append(SciAnalysis_PATH)

🛠️ Change this to your actual SciAnalysis folder path. For example, if you cloned the repo to your Desktop:

SciAnalysis_PATH = 'C:\\Users\\YourName\\Desktop\\SciAnalysis\\SciAnalysis'

Make sure to:

  • Use double backslashes \ or a raw string r'C:\path'
  • Point to the SciAnalysis subfolder containing XSAnalysis/ and tools.py

📁2. Set the Mask Path

The mask is often used for excluding detector artifacts or bad pixels.

in CaliWS.yaml, Look for lines like:

mask_dir: "/nsls2/data/cms/legacy/xf11bm/software/SciAnalysis//SciAnalysis/XSAnalysis/masks/"
# mask_file: "Dectris/Pilatus800k_gaps-mask.png"
mask_file: "Dectris/Pilatus800k_vertical_gaps-mask.png"
custom_mask: "./Pilatus800_current-mask.png"

🛠️ Un-comment and change this to your actual mask file path (Example):

mask_dir = 'C:\\Users\\YourName\\Your_SciAnalysis_Path\\mask\\'

If you don’t have a mask, you can either:

  • Generate one from a white and black image.
  • Comment it out and proceed (some protocols will still work without a mask).

🧪3. Customize Input and Output Paths

Later in the script (typically inside a loop or batch block), define:

input_dir = '/path/to/data/'
output_dir = '/path/to/output/'

🛠️ Replace these with actual folder paths:

input_dir = 'C:\\Users\\YourName\\Desktop\\data\\'
output_dir = 'C:\\Users\\YourName\\Desktop\\results\\'

Ensure:

  • Data files (e.g., .tif, .h5, etc.) are present in input_dir
  • output_dir exists or will be created

🧬4. Customize or Add Protocols

SciAnalysis lets you define custom protocols by subclassing existing ones:

Example from the script:

protocols = [
    Protocols.sector_average(name='vertical', angle=0, dangle=20, ylog=True, plot_range=[0, 3.5, None, None],  gridlines=True, save_results = [ 'txt', 'plots' ]) ,
    Protocols.sector_average(name='horizontal', angle=90, dangle=20, ylog=True, plot_range=[0, 3.5, None, None],  gridlines=True, save_results = [ 'txt', 'plots' ]) ,
    Protocols.linecut_angle(q0=2.10, dq=0.05*2, name='linecut_angle_peak3',show_region='save') ,

    ]

You can:

  • Modify protocols to change parameters, saving behavior, or others

⚙️5. Batch Processing Configuration

Locate the file name selector like:

#pattern = '*flaton*'
#pattern = 'Ag*'
pattern = '*'
#pattern = '*71857*'

The pattern variable determines which files in your input_dir are processed:

  • '*' — Process all files.
  • 'Ag*' — Process files starting with “Ag”.
  • 'flaton' — Process files containing “flaton” anywhere in the filename.
  • '71857' — Process files with “71857” in the name.

✅ You can uncomment and customize any one of these lines to suit your data selection.

Locate batch processor like: 

# Run
########################################
print('Processing {} infiles...'.format(len(infiles)))
process.run(infiles, protocols, output_dir=output_dir, force=True)
  • force=True forces re-processing of all input files:
    • Even if results already exist (e.g., .xml, .png, .dat files), they will be overwritten.
    • Useful when you’ve changed protocols, masks, or input parameters and want to regenerate outputs.
  • If you want to skip already-processed files, change to: force = False

🚀

6. Run the Script

Open Anaconda Prompt or Command Prompt, navigate to the script folder:

cd C:\Users\YourName\Desktop\SciAnalysis\examples
python runXS.py

CMS Beamline Quick‑Start:

This Quick-Start Guide is for users starting Bluesky, Xi‑CAM & SciAnalysis at beamline workstations. In case of any software crash, start a new terminal and type the following command.

0) Before You Begin

  • Accounts & access

    • Ensure your BNL credentials, Duo/MFA, and CMS access are active.
    • Ensure your training is up to date.
    • Ensure you appear on the proposal/SAF experimenter list.

  • Data locations (examples—use your own)

    • Proposal root:

      /nsls2/data/cms/proposals/<cycle>/pass-<######>/

    • Experiment folder:

      /nsls2/data/cms/proposals/<cycle>/pass-<######>/experiments/<ExpName>/

    • User configuration or plan file (example path):

      /nsls2/data/cms/shared/config/bluesky/profile_collection/users/<cycle>/<user_name>/user_TSAXSWAXS.py

    • Typical SWAXS layout:

      <ExpName>/saxs/{raw,analysis}/

1) Start Bluesky (interactive beamline session)

  1. Sync your proposal to the beamline environment

    sync-experiment -b cms -p <proposal_id>

    Follow the prompts to sign in (Duo/MFA).

  2. Launch Bluesky UI shell

    bsui

  3. (Optional) Load a user configuration or plan file Replace the path below with the current cycle and file you need.

    %run -i /nsls2/data/cms/shared/config/bluesky/profile_collection/users/<cycle>/<user_name>/user_TSAXSWAXS.py

2) Launch Xi‑CAM (graphical data browsing)

  1. Switch to your user account

    su - <username>

  2. Activate the Xi‑CAM conda environment

    conda activate xi-cam-py3-2025

  3. Start Xi‑CAM

    xicam

  4. Open your raw data folder Navigate to something like:

    /nsls2/data/cms/proposals/<cycle>/pass-<######>/experiments/<ExpName>/saxs/raw

3) Run SciAnalysis (batch analysis)

  1. Switch to your user account (if needed)

    su - <username>

  2. Prepare your analysis script Copy your runXS.py into the experiment’s analysis folder:

    cp /path/to/your/runXS.py \
   /nsls2/data/cms/proposals/<cycle>/pass-<######>/experiments/<ExpName>/saxs/analysis/

  3. Open the analysis folder in VS Code for editing

    code /nsls2/data/cms/proposals/<cycle>/pass-<######>/experiments/<ExpName>/saxs/analysis/
# edit runXS.py as needed

  4. Activate the analysis environment

    conda activate <analysis-env>

  5. Run the analysis

    cd /nsls2/data/cms/proposals/<cycle>/pass-<######>/experiments/<ExpName>/saxs/analysis/
python runXS.py

Outputs typically appear under the same analysis/ folder (e.g., plots, .dat files, logs). Adjust paths inside runXS.py if you use WAXS or alternate layouts.

4) Common Layout Reference (examples)

/nsls2/data/cms/proposals/
  └── <cycle>/
      └── pass-<######>/
          └── experiments/
              └── <ExpName>/
                  ├── saxs/
                  │   ├── raw/
                  │   └── analysis/
                  └── waxs/
                      ├── raw/
                      └── analysis/

5) Quick Troubleshooting

  • Permission denied → Confirm you’re on the approved experimenter list for the proposal/pass; re-login after updates.
  • Xi‑CAM won’t start → Ensure the correct conda env is active.
  • Analysis can’t find files → Double-check <cycle>, <######>, <ExpName> and that your runXS.py points to raw/ and writes to analysis/.

Appendix: Placeholder Keys

  • <cycle>: NSLS‑II run cycle (e.g., 2025-2).
  • <######>: Your pass number.
  • <ExpName>: Your experiment name/folder under experiments/.
  • <proposal_id>: Your proposal identifier used with sync-experiment.
  • <username>: Your BNL/CMS account username.
  • <analysis-env>: The conda environment for your analysis workflow.

Robot Sample Changer — High-Throughput Static GI-SAXS/WAXS

This guide explains how to use the CMS robot sample changer for high-throughput static GI-SAXS/WAXS experiments. It is written for beamline users and staff. Basic familiarity with the Python/Bluesky IPython console is helpful.

Key files

  • startup/user_collection/user_static.py: User-facing configuration file where you define samples, holders, default exposure times, incident angles, and the queue. Beamline staff should handle beamline-specific settings (calibration, detector geometry, helper functions).

Overview

  • The holder class used at CMS is typically GIBar_Custom. Each holder contains multiple sample slots.
  • The robot moves holders from the garage to the sample stage, one holder at a time, for measurement and then returns the holder to the garage.
  • For each sample the automated sequence will: put the beamline in alignment mode, align the sample, switch to measurement mode, move detectors/motors to SAXS/WAXS positions, and perform measurements at the configured incident angles and exposure times.

Instructions

Before your beamtime

  • Work with beamline staff to confirm your experimental parameters: sample details, desired q-range and incident angles, exposure times, and number of samples/expected beamtime.
  • Users are welcome to ask for sample bars to be shipped to them so they can load samples prior to their arrival. Alternatively, 3D-printed sample bar models are available.
  • Users are encouraged to input their sample information into the Google spreadsheet prior to arrival.
  • If possible, test a single sample early in the shift to validate alignment and detector settings.

Day-of checklist

  1. Edit user_static.py (staff or staff-assisted user)
  • Open startup/user_collection/user_static.py in an editor (for example, VS Code).
  • Typical edits:

    • RE.md['experiment_alias_directory'] — set your experiment folder where data should be saved (staff or user) .

    • RE.md['userpy_alias_directory'] (staff) .

    • Detector calibration: cms.SAXS.setCalibration([...]) (staff).

    • Helper functions: confirm saxs_on(), swaxs_on(), waxs_on() positions (staff) .

    • Per-sample defaults: inside the Sample class set incident_angles_default, SAXS_time, WAXS_time, and naming_scheme as needed.

    • Add your samples to holders (near bottom of the file) using the existing holder commands, for example:

      hol1.addSampleSlotPosition(Sample('MySample1', **md), 1, 10, 'WAXS', incident_angles=[0.08,0.12], thickness=0.7)

    • If you use a Google Sheet to generate lines, copy-paste the formatted lines into the holder block. Verify indentation and syntax.

    • Add/remove holders from the queue by (un)commenting que.addHolderIntoQueue(...) lines. Check the holder-to-garage coordinates.

    • Save the file.

  1. Reload scripts in IPython

    %run -i startup/user_collection/user_static.py

  2. Console prompts and expected replies

  • The %run -i reload may print questions from helper code. Typical prompts and answers:
    • "Is there a holder on the stage? (y/n)" → answer y if the holder is physically on the stage, otherwise n.
    • "Is there a holder on the robot? (y/n)" → answer y if the holder is physically on the robot, otherwise n. This typically applies to some condistion that robot control is crashed or jammed.
    • "If yes, what is the holder?" → answer holder name like hol1
    • If you are unsure about, stop and ask beamline staff.
  1. Vacuum and detector pre-checks

  • Pump the sample chamber (only when instructed/authorized):

    cms.pumpSample()

  • Start or ensure WAXS detector is running:

    startWAXS()

  • Check the control screen (CSS) for:

    • Gate valve status
    • Photon shutter state
    • Detector readiness
  1. Quick motor/position checks

  • Use these to confirm holders and sample positions:

    hol1.listSamples()        # List samples and slots on hol1
hol1.gotoOrigin()         # Move holder to its saved origin
sam = hol1.gotoSample(1)   # Obtain sample 1
sam.gotoOrigin()          # Move sample motors to the saved origin

  • For a quick detector frame (alignment check) use a short exposure or a snapshot plan. Example:

    # Example: quick 0.5 s frame using the default detector
sam.snap(0.5)

  1. Run the queued holders

    que.runHolders()

  2. Monitor console output for errors such as document saving failures, read timeouts, or suspender triggers.

  • Avoid stopping the queue while the robot is moving a holder; wait for safe points or ask staff.
  1. Emergency stop and safe abort

  • If you must stop a running plan, you can interupt the script by hitting Ctrl+C, then use RE.abort(). After aborting, ensure the beam is off:

    RE.abort()
beam.off()

  1. End of experiment: venting

    cms.ventSample()

Common methods and examples

  • Holder/sample listing and movement:

    hol1.listSamples()
hol1.gotoOrigin()
sam = hol1.gotoSample(1)
sam.gotoOrigin()

  • Alignment and measurement (example sequence for one sample):

    sam.align()                 # run alignment routine 
sam.measureIncidentAngle(incident_angles, exposure_time=10, tiling='ygaps')

Manual robot operations (staff-only or supervised)

  • Pick and return holder (examples — confirm with staff):

    # By holder object
robot.pickHolder(hol1)
robot.returnHolder(hol1)

# Or by garage coordinates (row, column)
robot.pickHolder([1,1])
robot.returnHolder([1,1])

  • Run one holder's automated sequence:

    hol1.doSamples()

If you need help

  • If you encounter unexpected behavior (robot jam, communication errors, detector errors), stop and call beamline staff.

Contributor Guide

Welcome! This guide explains how to contribute to the CMS User Guide using mdBook.

How mdBook Works

  • All content lives in the src/ directory as Markdown files.
  • The book structure is defined in src/SUMMARY.md.
  • When you push changes to the main branch, the book is automatically rebuilt and published to GitHub Pages.

How to Add or Edit Content

Add a New Chapter/Page

  1. Create a new Markdown file in src/ (e.g., src/New_Chapter.md).
  2. Add a link to your new file in src/SUMMARY.md: 
    - [New Chapter](./New_Chapter.md)
  3. Commit and push your changes to main.

Edit Existing Content

  • Edit the relevant Markdown file in src/.
  • Commit and push your changes.

Organize Chapters

  • Use src/SUMMARY.md to set the order and hierarchy of chapters.
  • Indent chapters under parents for nesting.

Preview Locally (Optional)

  1. Install mdBook (if not already):
    • macOS: brew install mdbook
    • Linux: cargo install mdbook
    • Windows: Download from mdBook releases
  2. Run mdbook serve in the repo directory.
  3. Open http://localhost:3000 in your browser.

Best Practices

  • Always update src/SUMMARY.md when adding/removing/reordering chapters.
  • Use clear filenames and titles.
  • Preview locally before pushing.
  • Commit related changes together.

Need Help?

  • Open an issue or ask in the repository discussions.

Thank you for contributing!