Installation and Configuration
- C++11 compliant compiler (e.g., gcc 4.8+)
- Qt 5.3 or newer core, gui, network, and serialport modules and development files.
- Qwt 6.1 or newer (http://qwt.sourceforge.net/) compiled against Qt 5. Note that the Qwt binaries distributed with some Linux distributions, including openSUSE Leap 42.1, are compiled against Qt 4. Use of these binaries will cause the program to crash immediately on launch. The Qwt header files should be accessible under
<qwt6/****.h>. A symlink named qwt6 in /usr/local/include that points to the directory containing the Qwt header files is sufficient. - GNU Scientific Library 1.16 or newer together with a supported BLAS library. See the GSL documentation for a discussion of BLAS library options.
- Eigen3 Linear Algebra Template Library (http://eigen.tuxfamily.org/). This is a header-only library.
Copy the file config.pri.template to config.pri. This file, which is ignored by git, can be used to configure your hardware selections, which program features are enabled, and any other compilation-related features that you require for your system. The config.pri file is processed by qmake; see the qmake documentation (http://doc.qt.io/qt-5/qmake-manual.html) for a full description additional options.
#CONFIG += gpu-cuda: This line can be uncommented to enable GPU averaging with CUDA-capable GPUs. Note that the library files and headers required for CUDA are not included with BlackChirp, and must be obtained from NVIDIA (https://developer.nvidia.com/cuda-toolkit). See the section of config.pri titled "CUDA compiler configuration" for an example of how to automatically use the nvcc compiler to add GPU support.
CONFIG += hardware: This line can be commented out to build the program without any external hardware support. This mode can be useful for testing or developing the software, or for viewing data on a machine without access to a spectrometer. When activated, this mode will include a resource file with a 750k record for the FTMW oscilloscope to generate simulated data. However, because the program adds noise to the data, performance will be a bit slower than usual because data generation is more CPU-intensive.
#CONFIG += lif: The LIF module allows for a tunable pulsed laser and auxiliary oscilloscope to be incorporated with the program for recording laser-induced fluorescence and FTMW data simultaneously. This is currently a work-in-progress and may contain serious bugs. Uncomment the line to enable this mode.
#CONFIG += motor: The motor module is designed to control a three-axis motor stage mounted with a pressure transducer for making impact pressure measurements for uniform molecular beams. Uncomment this line to enable this mode.
#-----------------------------------------
# Library configuration
#-----------------------------------------
unix:!macx: LIBS += -lqwt -lgsl -lm -lgslcblas
An example of the necessary library definitions on a unix system (but not mac). If you have different library paths or include paths, these may be added here. See the qmake manual sections on libraries (http://doc.qt.io/qt-5/qmake-variable-reference.html#libs) and includes (http://doc.qt.io/qt-5/qmake-variable-reference.html#includepath) for more information on how to reference libraries and headers.
#------------------------------------------------
# The following defines select hardware implementations.
# -----------------------------------------------
# FTMW Oscilloscope (0 = virtual, 1 = DSA71604C, 2 = MSO72004C, 3 = M4i2220x8)
FTMWSCOPE=2
#AWG (0 = virtual, 1 = AWG70002A, 2 = AWG7122B, 3 = AD9914, 4=M8195A)
AWG=2
#Clocks. Include in a space-delimited list, up to 5 numbers
#Definitions: (0 = FixedClock, 1 = Valon5009, 2 = Valon2015)
#For example:
#CLOCKS=0 0 1 3 2
CLOCKS=0 0
#Pulse generator (0 = virtual, 1 = Quantum Composers 9528+, 2 = Quantum Composers 9518)
PGEN=2
#Flow Controller (0 = virtual, 1 = MKS 647C)
FC=1
#IO Board (0 = virtual, 1 = Labjack U3)
IOBOARD=1
#GPIB controller (-1 = none, 0 = virtual, 1 = Prologix GPIB-LAN)
GPIB=-1
#pressure controller (-1 = none, 0 = virtual, 1 = Intellisys IQ Plus)
PC=-1
###### LIF ONLY #####
#LIF Oscilloscope (0 = virtual, 1 = DPO3012)
LIFSCOPE=1
##### END LIF ONLY #####
##### MOTOR ONLY #####
#Motor controller (0 = virtual, 1 = SCX11)
MOTOR=1
#Motor scope (0 = virtual, 1 = Pico2206B)
MOTORSCOPE=1
##### END MOTOR ONLY #####
}
In this section, you can select which implementations of different hardware devices you require. Simply use the appropriate number to indicate which implementation should be used. As new devices are implemented, the config.pri.template file will be updated to reflect the changes.
Devices with number 0 are 'virtual.' In this case, the program will simulate that piece of hardware. In addition, some pieces of hardware can be completely disabled by selecting -1. The hardware will not exist at all within the software, and some program options will be unavailable.
Anytime the config.pri file is edited, the entire program must be rebuilt for changes to take effect. If you use the Qt Creator IDE, this can be accomplished by selecting "Run qmake" and "Rebuild project." Otherwise, a "make clean" followed by "qmake" (with the appropriate spec file) and "make" should suffice.
BlackChirp stores all of its data (with the exception of user-specific display settings) under a single directory. By default, BlackChirp is configured to use the directory /home/data on UNIX systems and C:\data on Windows systems. The default behavior can be overridden by setting a system environment variable named BC_DATADIR. On UNIX, the best way to do this is by adding an entry to /etc/profile (or /etc/profile.local to prevent system updates from overwriting your changes). On Windows, the environment variable can be set from the GUI or by using the SETX command on the command prompt. This directory must exist and be writable by any users who will use BlackChirp before running the program. Note that if you change the BC_DATADIR environment variable on a Linux system, the program will generate a new config file, so all stored settings (e.g. communication information, last used settings, etc) will be lost. These can be recovered by copying over some or all of the BlackChirp.conf file located in OLD_BC_DATADIR/CrabtreeLab. On Mac OSX and Windows, the information will be preserved, but you may wish to reset the exptNum variable in the system settings (see QSettings) to restart experiment numbering from 1.
Use caution if you intend to reset the experiment numbering in the program settings. BlackChirp will overwrite any previously acquired experiment with the same number without warning if the BC_DATADIR value has not been changed.
After successfully compiling BlackChirp and launching the program, you will need to configure your instrument settings in the Hardware>Communication menu:
Select the device you wish to configure from the appropriate dropdown menu (the menu will be automatically populated with any attached devices), enter its settings, and press the "Test Connection" button. Any problems that occur during the communication test will be reported. To test all devices at once, select Hardware>Test all connections.
For many pieces of hardware, parameters such as min and max values etc are generally stored in the system settings where they may be changed (with caution) if needed. On Linux, these settings are stored in a text file located at BC_DATADIR/CrabtreeLab/BlackChirp.conf; on Mac OSX, they are stored using the CFPreferences API, and on Windows, settings are stored in the system registry. See the QSettings documentation for more details.
Once BlackChirp has established communication successfully with all devices, the remainder of the program will be enabled for use.