spec

Software for Diffraction

changes

Highlights for spec release 6.12

March 9, 2024 - RELEASE 6.12.05

IMPROVEMENTS

Improved List Navigation In Configuration Editor

The drop down lists in the edconf hardware configuration editor can now be navigated by typing multiple characters to match an entry. Previously only the first character of an entry was used for matching. Also, the the characters j and k, previously used for navigation, are now used for matching, but new ^P and ^N key entries are available to move up or down by one line. Type ? in the configuration editor for a list of commands.

Improved prdef For Embedded Single Quotes

The prdef command will now display the macro definition as a string delimited by double quotes if the definition contains unescaped single quotes. Previously, prdef would always delimit the definition with single quotes. If the definition used unescaped single quotes, the prdef output would not be suitable for reading back into spec.

New STATE_FILE Built-in Global Variable

A STATE_FILE built-in global parameter is now created that is set to the full path name of the user state file. The save_state macro will use its value, which allows the macro to work even if spec was invoked with the -T or -U flags, which create alternate tty or user names that are used to name the spec session's associated state file.

FIXES

Fix For Scaler Screen Of Configuration Editor

A bug in the edconf hardware configuration editor, where canceling a change in the drop down list of controller types on the Scaler screen would cause the choice to reset to the first item in the controller list, has been fixed.

HARDWARE

Trinamic TMCL Motor Controllers Updates

Trinamic TMCL motor controllers models TMCM-1180 and TMCM-1260 are now tested and working with spec. Additional TMCM models (1021, 1111, 1160, 1241, 1290, 3212, 3214, 3230, 3351, 6110 and 6212) should also work with spec, although the code has not yet been tested with the corresponding hardware. In addition, the parameter information (description, range, access) displayed with the "dump" and "gdump" motor_par() commands should now always be appropriate to the associated model. Also, those commands now take an optional pattern argument to only show parameters whose description matches the pattern. Finally, a "get_ain" motor_par() command is available to read the analog inputs. See the tmcl help file for details.

Fix For Excess Memory Consumption With MCA/Image Macro Hardware

An issue, where each mca_get()/mca_sget()/image_get() call with macro hardware devices would allocate memory for a temporary array that wouldn't be freed until a return to the main spec prompt, has been addressed. Previously, for example, memory usage in a scan would grow by the size of the data array for each point when reading from an MCA or image macro hardware device. For a scan with many points, the memory growth and associated overhead could slow performance.

Fix For epics_get() Reconnection

Previously, an epics_get() in a loop such as:

for (;;) { p epics_get(PV); sleep(1) }

would never reconnect following a channel access "Virtual circuit disconnect" event (such as loss of an Ethernet connection) even after the hardware connection was restored. However, spec would remake the connection after returning to the main prompt. With this spec release, the epics_get() function will take care of remaking the connection. Note, adding a call of wait(0x28) within the loop would be sufficient to regain the connection with prior spec releases. See the wait help file.

Fix For Physik Instrumente GCS-2 Motor Controller Initialization

A problem with spec's support for the Physik Instrumente GCS-2 motor controllers where the initial read of the command list could time out on slower interfaces has been fixed.

Option To Set Pause For Tsuji Controllers After Move Start

A new "mdelay" motor_par() option is available for Tsuji PM16C-02/04 motor controllers. The value (in seconds) is a sleep time for spec to pause after sending commands to start one or more motors on the controller. Some users report occasional communication failures if spec immediately requests status after staring a multiple motor move. Values on the order of 0.1 seconds should give the controller time to prepare to receive new commands. The motor_par() mnemonic argument is any motor associated with a Tsuji PM16C. The setting is global for all configured PM16C controllers and is saved in the state file. The default value is zero.

MACROS

Fix For Recently Broken savmac

An update to the savmac macro in spec release 6.11.02 to use fprintf() instead of the deprecated on() and off() functions had a bug that prevented printing the left parenthesis of macro functions with no arguments. That error is fixed in this release.

February 19, 2024 - RELEASE 6.12.04

FIXES

Fix For array_dump() Crash

Bugs in array_dump()/data_dump() (it is the same code for both) that could result in a crash due to memory corruption have been fixed.

MACROS

Standard Macro Tuneups

The mstartup macro will no longer prompt for parameters associated with geometry motors in a geometry-less configuration. The chk_acq_using macro will no longer produce error messages about undefined ROI_INFO or ACQ_flags when called by roi_reconf() if no acquisition or ROI actions are configured. The newfile macro will behave sensibly if DATAFILE and/or DATAFILE_TEMPLATE are unset or set to the null string.

HARDWARE

Fix For TMCL Parameter Restore Feature

A bug introduced in spec release 6.10.03 that partially broke the parameter restore feature for the TMCL motor controllers has been fixed. The bug prevented the restoration of parameters on other than the first motor on a particular controller board under certain conditions. The attempt to restore parameters occurs when spec detects the power has been cycled on a particular board, which erases all volatile parameter values. The skip of additional motors occurred after spec restored the value of an optional parameter. If there were no optional parameters, spec would continue to the next motor.

Eiger Server Now Works With acq_setup Macros For ROIs

The region-of-interest (ROI) counters implemented in the new acquisition macros can now be used with the eiger_server server hardware support. The macro file eiger_roi.mac is now obsolete. It is currently still included in the spec distribution, but is not installed. See the acq help file for details on configuring ROI counters.

January 24, 2024 - RELEASE 6.12.03

IMPROVEMENTS

New changes Help File On the Web

The certif.com web site now includes a single changes help file that includes all the update notes in reverse chronological order starting from the latest release and going back to release 2.5 from May 11, 1988. Such a file has been included in the spec distribution for some time.

MACROS

Fix For Motorless flyscan Macro

An error where the dwell time per point for motorless fly scans was miscalculated has been fixed.

New SCAN_D_shared Macro

A new SCAN_D_shared macro is defined by default as shared to put the SCAN_D scan data array in shared memory. Define SCAN_D_shared as an empty string to make SCAN_D an ordinary non-shared data array.

PYTHON

Updates To splot, eiger_server and pyspec

With this release, the Python utilities and packages included with spec have updates to continue to install and run with newer Python releases. Also, some recent changes that broke the utilities with older Python releases have been addressed.

December 4, 2023 - RELEASE 6.12.02

IMPROVEMENTS

Automatic Directory Creation When Opening Files

Functions that open files will now attempt to create directories as needed when they are part of a file path. Built-in functions that use this capability are open(), on(), fprintf(), array_dump() and data_dump(). In addition, directories will be created as needed for log files specified on the spec startup command line with the -l logfile option and for the daemon-mode log file, if daemon mode is active. If directory creation fails, for example, due to insufficient permissions, the functions will fail in the same way as if the file could not be opened.

More Flexible Syntax With @ Indirection

The @ indirection operator takes the string value of the item following and turns that into a variable name. For example:

var = "PI"; print @var

would print 3.14159. When the @ indirection operator precedes something in parentheses, previously, that something could only be a variable or associative array element. With this release, the item in parenthesis can be any expression that evaluates to a variable name on which the @ can operate.

Additional Install Option

The Install script to install the spec distribution now accepts a -y flag to go along with the recently introduced -C flag to remove files that get recompiled. The -y flag means "yes", remove the files without asking for confirmation.

Updated help Macro

The help topics displayed when the help macro is invoked without an argument are now organized by category. In addition, multiple topics can be used as arguments or entered when prompted.

MACROS

Update For When DATA_DIR Is Prepended To DATAFILE

Previously, if DATAFILE didn't contain a / character and if DATA_DIR existed, the newfile macro would prepend DATA_DIR to DATAFILE to create the data file path. As the newfile macro now supports templates and a directory that is possibly specified via a template can be included in the path, and since spec can now create directories automatically, the rule for prepending DATA_DIR is changed. Now, DATA_DIR is prepended if DATAFILE doesn't begin with a / or ./ and if DATA_DIR exists.

Note, the newfile macro tests whether DATA_DIR exists before using it. The macro doesn't use the automatic directory creation feature for DATA_DIR.

November 16, 2023 - Release 6.12.01-3

FIXES

Fix To Ensure HDF5 "gzip" Option Is Available On All Platforms

A build issue, where support for the "gzip" compression option for creating HDF5 files was not included in spec's distributed libhdf5.a library for some Linux platforms, has been fixed. One can check whether compression is available using the following command on the library in the spec distribution directory:

nm libhdf5.a | grep compress2

If the output is "U _compress2", then compression is available. If compression is not available, one can update the spec distribution, or one can build a local version of libhdf5.a and relink spec using that libhdf5.a. When building the HDF5 library locally, be sure the zlib development package is installed on the system. Note, the spec distribution includes a precompiled libzlib.a. Sources corresponding to the HDF5 and zlib libraries included in the current spec distribution can be downloaded at certif.com/downloads/extras/hdf5.tgz and certif.com/downloads/extras/zlib.tgz.

Fix For Possible h5_data() Crash

Previously, if an optional argument to h5_data() specified a data type that was wider than the native data type of the array being written (say "double" for a "short" array), the function call could lead to a crash. That issue has been fixed.

November 11, 2023 - RELEASE 6.12.01-2

FIXES

The queue() Function Now Works

The new experimental queue() function described in the spec release 6.11.03 was inadvertently disabled by a last minute edit in that release. The function is now available. See the queue help file.

November 7, 2023 - RELEASE 6.12.01-1

MACROS

Fix For setor1 Macro Typo

A typo in the setor1 geometry macro introduced in spec release 6.11.02 has been fixed.

October 17, 2023 - RELEASE 6.12.01

IMPROVEMENTS

Can Now Use cdef() With Macro Functions

The cdef() chained-macro built-in function can now be used to define spec macro functions. Previously, cdef() was only available for ordinary macros. Unlike ordinary macros, which are expanded very early in the input stream, macro functions are parsed and executed as encountered after parsing and during execution of the encompassing input. In addition, macro functions can return a value. With this spec release, if any of the cdef() calls that define parts of a chained macro include parenthesis after the macro name, the macro will become a macro function. spec will automatically add an initial and final curly bracket to the pieces of the chained macro. Note, though, cdef() macro functions don't currently allow arguments in the definition. However, a cdef()-defined macro function can be called with arguments that can be accessed in the definitions using the argc, argv[] or arg1, arg2, ... features. See the macros help file for details.

New argv[] For Macro Functions and Other Improvements

All arguments to macro functions can now be accessed using the automatically created local associative array-like variable argv[]. Elements are numbered starting from "1". In addition to representing numbers and strings, the argv[] elements can represent another associative array or a data array, matching the data type passed to the macro function. In addition, the symbols arg1, arg2, etc., are created for all arguments. Previously, the symbols were only created for arguments beyond those included in the macro definition. See the macros help file for details and limitations in accessing elements of argv[] that represent arrays.

New "date_format" spec_par() Parameter

Previously, spec used the US format for time and date which puts the month ahead of the day. It is now possible to specify the default format for the string returned by spec's built-in date() function. A call of:

spec_par("date_format", "%a %d %b %T %Y")

would set the date() output to this format:

Tue 29 Aug 20:46:50 2023

instead of the default format which continues to be "%a %b %d %T %Y", producing:

Tue Aug 29 20:46:50 2023

Any format recognized by the strftime() library function is accepted. Beware of selecting a format that leaves out important information. As with most spec_par() parameters, the value is saved in the user's state file. See the spec_par help file.

MACROS

New file_from_template() Macro For Data Files

A new file_from_template() macro is used with the newfile macro to allow data file names to include conversion specifications that are replaced with time or date values or specific spec parameters. The time and date conversions are those supported by the C library strftime() function and used by spec's date() function. Additional conversions are available for the spec data file name, scan number, point number and others. See the newfile help file for further information.

newfile Macro Now Accepts File Template

The newfile macro now takes a file template argument rather than necessarily a file or path name. Each call to newfile will create the DATAFILE name from the template, using the current date and time, if such conversions are present in the template. The macros that write to the data file will not automatically update DATAFILE if, for example, elements of the current date are included in the template and the current date changes during a spec session. However, the new usage newfile -u will update DATAFILE using the current template, stored in the new standard global variable DATAFILE_TEMPLATE.

New Options For Saving MCA/Image Data

The acqsetup macro now includes an option to set whether and how to save the acquired MCA or image data. Spectra can be saved in the standard spec data file or in one or more separate files. If separate files are chosen, there are options to use one additional file for all spectra, one file per scan, one file per data point or one file per array. In addition, one can configure spec to automatically generate file names, or one can define a template for saving such data, which can include conversion sequences for the standard spec data file name, scan number, point number and array name, along with the other strftime() conversions. Currently only ASCII save files are supported. See the acq and newfile help files.

Changes For How ACQ Devices Are Read In the Macros

The new get_acqdev macro, which reads all the enabled MCA and image devices has been relocated to the standard get_counts macro, which is the lowest level macro for reading counters. Previously, get_acqdev was part of the count, _pcount (associated with powder mode) and _upd_count (associated with updated counting) macros. This change ensures that the ct macro and others will read enabled devices. Note, though, if reading such devices is slow, one might want to use the disable/enable macros to temporarily stop the devices from being read. See the disable help file.

Updated chk_move, chk_count and chk_acq Macros

The chk_move, chk_count and chk_acq macros now include a call of the new macro functions user_chk_move(), user_chk_count() and user_chk_acq(), respectively. These macro functions are defined using the cdef() chained macro function. The standard macros create a starting definition for each of these macro functions that simply returns a zero. The macro functions can be redefined locally, as needed, to return values associated with user hardware that indicate whether the associated device is busy. Note, the chk_move and chk_count macros included non-blocking calls of the built-in wait() function and are used in the standard spec macros for updated moving and counting. The chk_acq() macro also includes a wait() call, but isn't currently used with the standard macros.

In addition, tests of the values of the global variables USER_CHK_MOVE, USER_CHK_COUNT and USER_CHK_ACQ are no longer included in the chk_* macros. It is doubtful that these variables have ever been used. See the util.mac file in the spec distribution for information on how to restore inclusion of these variables, if it turns out someone does use them.

Fix For flyscan When Using Pitch Rather Than Intervals

The flysetup macro prompts for the choice of using "intervals" or "pitch" for setting the number of points in the scan. An issue with the calculations when using "pitch" has been fixed. The bug dates from spec release 6.10.05, which introduced macro code to round the number of intervals to solve the problem when an intervals argument is an expression involving floating point values and the integer value of that expression may be one less than the expected value. Integer rounding wasn't appropriate if the argument was the fly-scan bin width.

HARDWARE

Additional Support For Physik Instrumente GCS-2 Controllers

The initial support for Physik Instrumente GCS-2 motor controllers now includes the model E-272.3SDA in addition to models C-663.12 and C-863.11. There are some changes to the code structure to accommodate the new model. The code is now even more likely to work with additional models, although fine tuning may still be needed. See the pi_gcs help file for details.

FIXES

Fix For tango_put() Crash On Missing Input

An old bug (since 2014 spec release 6.02.00), where a call to tango_put() that doesn't supply a value argument for the corresponding attribute argument could lead to a segmentation fault, has been fixed.

Crash With Deeply Recursive Macros Fixed

Previously, recursive macro calls deeper than 169 would cause a crash. That limit is still present, but spec now prints an error message and returns to the command prompt.

Fix For Recently Updated getline()

An issue with the recent updates to the getline() function to maintain current position in multiple files has been fixed. Previously, if an open file was modified, spec might not reopen the file, thus returning stale content. When using getline() to read the next line of a file, spec saves the current byte offset. Note, though, if content is removed or added before that offset, the string returned by getline() may not be the next line after the last one read.