Skip to main content
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Sample State System

Sample State Table Panel

This table is designed for triple-axis instruments. Unlike the sample table this allows you to track information about a sample which may change. For example, you could measure and record a sample's lattice at several different temperatures (states) and record each lattice in this table. Here is a list of state properties:

sampleStateID - pre experiment unique sample state id

sampleId - sample id that can be linked to the sample state

Crystal System - description of the crystal structure (Cubic, Triclinic, etc.)

lattice parameters (a, b, c, Alpha, Beta, Gamma)

reflection planes (refPlane1, refPlane2Two of the crystal's HKL vectors which are in the plane of the floor. refPlane1 will point perpendicular to the beam, when sampleTheta = 0. refPlane2 will point against the beam, at some angle, when sampleTheta=0.

a3Zero - The zero for the sampleTheta motor when this sample state was aligned.

chiZero - The zero for the chi motor when this sample state was aligned.

tilts (alighedLowerTilt, alighnedUpperTiltThe position of the tilt motors when this sample state was aligned.

temp - optional temp value associated with the sample state

other - optional text input for any miscellaneous information

sample state table image
Sample State Table​​​​​​

Basic Sample State Controls

Each row of the Sample State Table defines a state. The basic controls are as follows:

  • "Add Sample State" - Creates a new sample state. Each new sample state is automatically given a unique localID and UUID (see sample system  for more info). Additionally, the first sample state which is created is automatically made the active one.
  • "Delete Sample State(s)", "Copy Sample State(s)" - Delete or copy selected sample states
  • "Clear " - Removes all samples states from the table.
  • "Make Selected Sample State Active" - Makes the selected sample state active by moving sampleStateId --> localID for that sample state. Additionally:
    • the active sample state's row is highlighted in this table and the localID column will contain the additional text "(current)".
    • if there is a sample (sampleID) associated with the current sample state, that sample will also become active by moving sampleId --> localID

Sample State Details

In the client, Sample State Table and it's behavior is designed to be very similar to sample table. Sample state also has a notion of being active (currently in the beam). As we mentioned above.  Sample State can also change linked sample's activeness, but not the other way around, because single sample can be associated with multiple sample states. 

The sampleStateId (sampleStateId.primaryNode) node defines the current state of the sample, which NICE is in the beam. This node's value is a number corresponding to the value of the localID property of one of the sample states. It can also be 0 which denotes that no sample state is current. 

In addition, the values associated with the current sample state are reflected in sampleState device's nodes. When NICE writes data files it will automatically record current sample state as any other device. By changing sampleStateID during trajectory, you'll be able to track what state properties you were measuring in any given data file and even search for your files later using this information.

Note: for some instruments (bt7 for example, sampleState device is marked as STATE, meaning its node values can changes during the measurement.  And for other instruments (MACS) it's more desirable if the sampleState stays STATIC (does not change).  The users prefer to change the state manually before running a trajectory.


Created January 4, 2023, Updated April 10, 2023