SANS Commands

Contains a list of commands relevant to small angle scattering instruments.

Sample

Sample GetApert
Sample GetLabel
Sample GetProperty
Sample GetThk
Sample GetTrans
Sample Info
Sample SetApert
Sample SetLabel
Sample SetProperty
Sample SetThk
Sample SetTrans

Sample GetApert

Brief Description

Retrieves sample aperture if it is available.

Syntax

Sample GetApert

Sample GetLabel

Brief Description

Retrieves sample label if it is available.

Syntax

Sample GetLabel

Sample GetProperty

Brief Description

Retrieves a value of a given sample property.

Syntax

Sample GetProperty Property

Required Parameters

Property is one of the following: Apert, Label, Thk, or Trans.

Sample GetThk

Brief Description

Retrieves sample thickness if it is available.

Syntax

Sample GetThk

Sample GetTrans

Brief Description

Retrieves sample transmission if it is available.

Syntax

Sample GetTrans

Sample Info

Brief Description

Display in the console the information about sample including sample aperture, thickness, transmission, and description.

Syntax

Sample Info

Sample SetApert

Brief Description

Sets sample aperture.

Syntax

Sample SetApert Apert

Required Parameters

Apert is a float defining sample aperture diameter (measured in mm).

Examples

Sample SetApert 0.1

Sets sample aperture diameter to 0.1 mm.

Sample SetLabel

Brief Description

Sets sample label to a given value.

Syntax

Sample SetLabel Label

Required Parameters

Label is a string defining new value of sample label. Maximum length of Label is 60 symbols.

Sample SetProperty

Brief Description

Sets a value of sample property.

Syntax

Sample SetProperty Property Value

Required Arguments

Property is one of the following sample properties: Apert, Label, Thk, or Trans.

Value is a value to which the property will be set.

Examples

Sample SetProperty Apert 0.1

Sets sample aperture diameter to 0.1 mm.

Sample SetThk

Brief Description

Sets sample thickness.

Syntax

Sample SetThk Thk

Required Arguments

Thk is a float defining new value of sample thickness (measured in cm).

Sample SetTrans

Brief Description

Sets sample transmission.

Syntax

Sample SetTrans Trans

Required Arguments

Trans is a float defining new value of sample transmission.

Scan

Scans are described as an instrument state or a sequence of states at which measurements are made. Virtual devices and sample environment devices can be used in scan description just like any other device.

The following commands can be used to do manipulations on scans and scan lists. Scan AppendList
Scan ChkOverwrite
Scan ClearList
Scan CopyRange
Scan CurrentToList
Scan CutRange
Scan Delete
Scan DeleteIndex
Scan Descr
Scan DescrToList
Scan DryRun
Scan Howlong
Scan InitList
Scan InitScan
Scan List
Scan ListBackup
Scan ListCopy
Scan ListDescr
Scan Load
Scan LoadConfig
Scan LoadList
Scan Modify
Scan Operation
Scan PasteRange
Scan PatchRange
Scan Run
Scan SaveConfig
Scan SaveConfigID
Scan Set
Scan ThinLoad

Scan Descriptions

A string describing a scan is used to transfer the scan information between processes. This string is parsed and translated into a sequence of instrument states.

In some cases, additional parameters might be needed for the scan description to be complete. Required scan parameters for SANS instruments include:

  • JType = SANSAUTO: associates a given scan with Sans-specific Automatic Data interface

  • SANSSTOP = 0 or 1: a STOP attribute indicating the end of run range

  • Counts = N: number of seconds that will be counted for at each prefactor

  • Prefac = N: number of prefactors

  • Filename = S: a prefix for data files

  • Comment = S: sample label

In addition, some scans may define positions of selected devices that will be moved before counts are measured. For example, the following scan will move GuideTable to 7 guides, BeamStop to 2 and Temperature device to 300 followed by counting for 10 seconds:

Scan:Counts=10:Prefac=1:Filename=test:Comment=ICE:Angle=Guidetable=7: Angle=Beamstop=2:Angle=Temp=300:JType=SANSAUTO:SANSSTOP=0

The description string should always start with the word Scan. Colons separate tokens and values in a list are separated by a space. Each token is made of a field descriptor following by an equal (=) sign and one or several values. The list of available field descriptors is:

  • Title: Title of the scan.

  • Comment: Sample Label or other comment.

  • Filename: A string that will be added at the beginning of the data file name.

  • Counts: The number of counts for the point.

  • Prefac: A multiplication factor for the number of counts.

  • Npts: The number of points in the scan. Defaults to 1.

  • Angle: A complete list of device positions to be visited before counting is performed: Angle=Device name=Position1 Position2

  • Range: is an alternative to Angle that gives the number of devices values as a functional relation. The format is one of the following: Range=Device name=Range center Increment, Range=Device name=Range start Range stop S, or Range=Device name=Range start Increment I.

    The Range token can be used to specify any value, including Temp and MagField. Values that are constant throughout the scan can also be specified with a zero increment.

  • Sample: Sample property given in the form: Sample=Property name=Property value. For example, Sample=Thk=0.1 will set sample thickness to 0.1; Sample=Trans=1.0 will set sample transmission to 1.

  • PresetDevicesProperties: A property of environment device that will be preset at the beginning of scan execution. For example, PresetDevicesProperty=Temp tolerance 1.0 will preset temperature set point error to 1; PresetDevicesProperty=Temp timeout 5.0 will preset temperature timeout to 5 seconds.

  • SANSRheoPulses: a number of Rheometer pulses.

  • Timeout: Time after which the preset counter will be stopped regardless of whether it has reached its preset value.

  • HoldPoint: Holding time before the preset counter is started at each point.

  • HoldScan: Holding time before the preset counter is started for the first point of a scan.

Any additional tokens can be appended to the scan description as meta data. These additional tokens must be separated by colons.

Scans in ICE are stored in a list in memory. The scan descriptions contained in the list are available to users to run on an instrument. In order to save scans for repeated uses over time, the scan list must be backed up to disk. Several commands exist for manipulating the scan list and moving its contents to and from disk.

Scan AppendList

Brief Description

Appends scans from a given file to the scan list.

Note that this can lead to entries in the current scanlist being overwritten. Use Scan ChkOverwrite to see which scans would be overwritten.

Syntax

Scan AppendList Filename [option]

Required Parameters

Filename is the name of the file content of which will be appended to the scan list.

Options

-K

Prevents scans from being overwritten.

Scan ChkOverwrite

Brief Description

Returns the list of scans which would be overwritten by loading a list of scans from a file. See also Scan LoadList and Scan AppendList commands.

Syntax

Scan ChkOverwrite Filename

Required Arguments

Filename is the name of the file to check for conflicts which would overwrite the current scan list.

Scan Clearlist

Brief Description

Clears out all scans currently in the scan list. If those scans have not been backed up, they will be lost.

Syntax

Scan ClearList

Scan CopyRange

Brief Description

Copies a range of scans in the scan list into location starting from a given position.

Syntax

Scan CopyRange Start End Destination

Required Arguments

Start is the an integer number greater than 0 that defines the beginning of the range of scans that will be copied.

End is the an integer number greater or equal to Start that defines the end of the range of scans that will be copied.

Destination is the an integer number greater than 0 that defines position to which selected set of scans will be copied. Note that if Destination is greater than the number of scans in the list, selected scans will be put immediately after the last scan in the list.

Examples

Scan CopyRange 1 5 10

Copies scans 1 through 5 into positions 10 through 14.

Scan CurrentToList

Brief Description

Puts the current scan description in the scan list on the server under a specified name. Note that if a target scan already exists in the list, it will be replaced.

Syntax

Scan CurrentToList Name

Required Arguments

Name is a positive integer indicating the place in the scan list to which the scan should be stored.

Scan CutRange

Brief Description

Removes a range of scans from the scan list and saves them in memory to be later used with Scan Paste command.

Syntax

Scan CutRange Start End

Required Arguments

Start is the an integer number greater than 0 that defines the beginning of the range of scans that will be removed.

End is the an integer number greater or equal to Start that defines the end of the range of scans that will be removed.

Scan Delete

Brief Description

Deletes a given scan from the scan list on the server.

Syntax

Scan Delete Name

Required Parameters

Name is a positive integer corresponding to the scan to be deleted.

Scan DeleteIndex

Brief Description

Deletes the scan list entry at a given list index position.

Syntax

Scan DeleteIndex Index

Required Parameters

Index is an integer representing the location of the item to be deleted in the scan list.

Scan Descr

Brief Description

Returns description of the current scan.

Syntax

Scan Descr

Scan DescrToList

Brief Description

Puts a given scan description into the scan list, under the given name. Note that if a target scan already exists in the list, it will be replaced.

Syntax

Scan DescrToList Name Description

Required Parameters

Name is a positive integer specifying position in the scan list to which the scan will be saved.

Description is a properly formatted scan description.

Scan DryRun

Brief Description

Dry runs a given the current scan by calculating device positions for each point in a scan. Each device position is then checked for validity such as being within preset limits. If scan name not given, dry runs the current scan.

Syntax

Scan DryRun Name

Required Arguments

Name is a positive integer specifying a scan of interest.

Scan Howlong

Brief Description

Computes the duration of a range of scans. If scan counts against Time, the duration of the scan will be set to the number of counts multiplied by the prefactor.

If scan counts against Monitor counts, a 3rd degree polynomial parameterization of the monitor rate as a function of an instrument-specific device will be used to estimate the rate at each point of the scan. The monitor rate predicted by the parameterization is scaled according to the stored monitor rate and the value of device it was measured at.

The Rate command should generally be run before Scan Howlong. If it has not been run when Scan Howlong for scans using monitor counts is run, Rate will be run automatically before a result is given.

Syntax

Scan HowLong Start End [options]

Required Parameters

Start is an integer greater than 0 that defines the beginning of the range of scans which duration will be estimated.

End is an integer greater or equal to Start that defines the end of the range of scans which duration will be estimated.

Options

-s

Instructs to return the result in seconds. Otherwise it will be in hours.

-o Overhead

Sets a default overhead, in seconds, that will be added to the time for each point. If there is a device with a higher movement overhead than the specified overhead, then that device's overhead will be added instead.

Additional Information

See also: Device GetOverhead and Device SetOverhead commands.

Execution behavior: Immediate.

Scan InitList

Brief Description

Initializes the scan list which includes removing all existing scans from the list and creating the default scan that fully describes current instrument state. For SANS, default scan will contain current positions of all devices.

Syntax

Scan InitList

Scan InitScan

Brief Description

Initializes the current scan and sets it to its first point. If the scan is already running, it will finish processing current point and will be re-initialized.

Syntax

Scan InitScan

Scan List

Brief Description

Retrieves the server’s list of scans.

Syntax

Scan List

Scan ListBackup

Brief Description

Saves the scan list to a file.

Syntax

Scan ListBackup Filename

Required Parameters

Filename is a name of file to which the scan list will be saved.

Additional Information

See also: Scan LoadList command.

Execution behavior: Immediate.

Scan ListCopy

Brief Description

Copy an entry in the scan list pointed by Source into the entry pointed by Destination. Note that if Destination already exists in the list, it will be replaced.

Syntax

Scan ListCopy Source Destination

Required Arguments

Source is a positive integer indicating scan to be copied.

Destination is a positive integer indicating the destination where the scan is to be copied.

Scan ListDescr

Brief Description

Retrieves the description of a given scan from the server.

Syntax

Scan ListDescr Name

Required Arguments

Name is a positive integer specifying the scan of interest.

Scan Load

Brief Description

For given scan name, the system reads the current scan description and appends it to the queue for future execution. The user may change scan description later without altering the already queued scan. The user may load multiple scans with the same name and different descriptions.

Syntax

Scan Load Name

Required Parameters

Name is a positive integer indicating a scan that will be loaded for execution.

Scan LoadConfig

Brief Description

Loads a scan from a given file into specified place(s) in the scan list.

Syntax

Scan LoadConfig Filename Scanname

Scan LoadConfig Filename Start End

Required Arguments

Filename is a name of file which contains a scan definition to be loaded. Note, that file extension .cfg is associated with SANS configuration files.

Scanname is a positive integer that specifies a scan number which description will be replaced with the description from a given file. Alternatively, the user can load description into a range of scans between Start and End.

Scan LoadList

Brief Description

Replaces the scan list with the list from a given file. See also Scan ListBackup command.

Syntax

Scan LoadList Filename

Required Arguments

Filename is a name of file from which to load scan list.

Scan Modify

Brief Description

Modifies the current scan by setting it to a given scan description.

Syntax

Scan Modify Description

Required Parameters

Description is a properly formatted scan description.

Scan Operation

Brief Description

Allows the user to apply changes to descriptions of several scans at once. This command will replace the values of specified scan parameters in the scan description with the values given by the user. If a certain scan parameter has not yet been defined for given scans, the parameter will be added.

Note that this command is intended for advanced users. The system will not prevent you from making changes which lead to invalid or inconsistent scans. See "Notes and Warnings" section below.

Syntax

Scan Operation Name1,Name2,... Changes

Required Parameters

Name1,Name2,... is a list of positive integers that specify individual scans to which changes will be applied. The list should be separated by commas and contain no spaces.

Changes is a list of settings for scan keyword attributes. Each attribute is an attribute name followed by the equals sign and a value. Different attributes are separated by commas. See Scan for definition of scan attributes.

Examples

Scan Operation 1,3 Counts=100,Angle=Temp=200

Changes scans 1 and 3 by setting the number of counts to 100 seconds and moving temperature device to 200.

Additional Information

Notes and Warnings: This command does not protect against breaking scans.

See also: scan description format.

Scan PasteRange

Brief Description

Inserts a range of scans which were previously copied into memory using Scan Cut command in a given position in the scan list.

Syntax

Scan PasteRange Destination

Required Arguments

Destination is the an integer number greater than 0 that defines position in which a set of scans will be inserted. Note that if Destination is greater than the number of scans in the list, selected scans will be appended to the end of scan list.

Scan PatchRange

Brief Description

Applies changes to the range of scans. Note that this command is intended for advanced users. The system will not prevent you from making changes which lead to invalid or inconsistent scans. See Notes and Warnings section below.

Syntax

Scan PatchRange Start End Changes

Required Arguments

Start is the an integer number greater than 0 that defines the beginning of the range of scans that will be changed.

End is the an integer number greater or equal to Start that defines the end of the range of scans that will be changed.

Changes is a comma-separated list of settings for scan keyword attributes. Each attribute is an attribute name followed by the equals sign and a value. See scan description format for definition of scan attributes.

Examples

Scan PatchRange 1 10 Counts=100,Angle=Temp=200

Changes scans 1 through 10 by setting the number of counts to 100 sec and moving temperature device to 200.

Additional Information

Notes and Warnings: This command does not protect against breaking scans.

See also: scan description format and Scan Patch panel documentation for Scan PatchRange GUI support.

Scan Run

Brief Description

Executes scans in a given range. Unless Scan Load command was used before Scan Run to copy scan definition to the queue for execution, Scan Run command will use the most recent scan version. Changes made to scan definition after execution begins will not have any effect.

Command Scan Runscan is equivalent to Scan Run.

Syntax

Scan Run Start End

Required Arguments

Start is the an integer number greater than 0 that defines the beginning of the range of scans that will be executed.

End is the an integer number greater or equal to Start that defines the end of the range of scans that will be executed.

Scan SaveConfig

Brief Description

Creates and saves a scan that fully describes current instrument state into a given file.

Syntax

Scan SaveConfig Filename [Additional parameters]

Required Parameters

Filename is a name of file to which a scan definition will be written. Note, that file extension .cfg is associated with SANS configuration files.

Optional Parameters

Additional parameters is a partial scan description (possibly empty) that overrides current instrument state in the created scan. See scan description format for further details.

Examples

Scan SaveConfig testConfig.cfg Counts=100:Sample=Thk=1

Retrieves all current device positions and properties, sample properties and global scan properties. These will subsequently be used to create scan description in which number of counts will be reset to 100 and Sample Thickness will be reset to 1. This scan will be saved to a file testConfig.cfg.

Scan SaveConfigID

Brief Description

Saves a given scan that to a specified file.

Syntax

Scan SaveConfigID Filename Scanname

Required Parameters

Filename is a name of file to which a scan definition will be written. Note, that file extension .cfg is associated with SANS configuration files.

Scanname is a positive integer specifying an existing scan that will be saved.

Scan Set

Brief Description

Sets current scan to a given scan description.

This command cannot be run if there is a scan in progress.

Syntax

Scan Set Description

Required Parameters

Description is a properly formatted scan description.

Scan ThinLoad

Brief Description

Appends a range of scans to the queue for execution. For all scans in a given range, the system reads the scan definition and appends it to the queue for future execution. The user may change scan definition up until the moment the scan execution starts at the server. These changes will apply to already queued as well as all future executions of the scan.

If one or more scans from a given range does not exist at the server, the system will create it with a description specific to the instrument. For SANS, default scan will be a STOP.

Syntax

Scan ThinLoad Start End

Required Parameters

Start is the an integer number greater than 0 that defines the beginning of the range of scans that will be loaded for execution.

End is the an integer number greater or equal to Start that defines the end of the range of scans that will be loaded for execution.