From: <ro...@us...> - 2012-06-06 14:00:08
|
Revision: 2009 http://nsclspectcl.svn.sourceforge.net/nsclspectcl/?rev=2009&view=rev Author: ron-fox Date: 2012-06-06 13:59:56 +0000 (Wed, 06 Jun 2012) Log Message: ----------- issue #972 - inform users of missing parameter definitions Modified Paths: -------------- branches/3.3-009-development/CHANGELOG branches/3.3-009-development/ccusb/Makefile.am branches/3.3-009-development/ccusb/ccusbSpecTcl.xml branches/3.3-009-development/ccusb/spectclconfig.tcl branches/3.3-009-development/doc/Commands/treeparameter.htm branches/3.3-009-development/vmusb/Makefile.am Added Paths: ----------- branches/3.3-009-development/vmusb/vmusb.xml Modified: branches/3.3-009-development/CHANGELOG =================================================================== --- branches/3.3-009-development/CHANGELOG 2012-05-18 17:49:41 UTC (rev 2008) +++ branches/3.3-009-development/CHANGELOG 2012-06-06 13:59:56 UTC (rev 2009) @@ -963,3 +963,5 @@ 3.3-009 - May 4, 2012 - Added cusbSpecTcl to the build. + - June 6, 2012 - Added vmusbSpecTcl to the build. + - Tell user about missing parameters array elements. Modified: branches/3.3-009-development/ccusb/Makefile.am =================================================================== --- branches/3.3-009-development/ccusb/Makefile.am 2012-05-18 17:49:41 UTC (rev 2008) +++ branches/3.3-009-development/ccusb/Makefile.am 2012-06-06 13:59:56 UTC (rev 2009) @@ -79,13 +79,13 @@ EXTRA_DIST=MakefileSkel.in \ spectclconfig.tcl \ - SpecTclRC.tcl + SpecTclRC.tcl ccusbSpecTcl.xml docs_built: ccusbSpecTcl.xml -$(MANDOCBOOK) man $< 2>/dev/null $(HTMLDOCBOOK) $< $(HCDOCBOOK) $< - dvipdf ccusbSpecTcl.pdf + dvipdf ccusbSpecTcl.dvi touch docs_built Modified: branches/3.3-009-development/ccusb/ccusbSpecTcl.xml =================================================================== --- branches/3.3-009-development/ccusb/ccusbSpecTcl.xml 2012-05-18 17:49:41 UTC (rev 2008) +++ branches/3.3-009-development/ccusb/ccusbSpecTcl.xml 2012-06-06 13:59:56 UTC (rev 2009) @@ -530,8 +530,9 @@ m_param2.Initialize("param2"); <co id='tree_2' /> m_param2.Bind(); - + m_initialized = true; } + } </programlisting> </example> @@ -735,7 +736,7 @@ </refmeta> <refnamediv> <refname>ccusbSpecTcl</refname> - <refpurpose>Sstarting the CCUSB SpecTcl.</refpurpose> + <refpurpose>Starting the CCUSB SpecTcl.</refpurpose> </refnamediv> <refsynopsisdiv> Modified: branches/3.3-009-development/ccusb/spectclconfig.tcl =================================================================== --- branches/3.3-009-development/ccusb/spectclconfig.tcl 2012-05-18 17:49:41 UTC (rev 2008) +++ branches/3.3-009-development/ccusb/spectclconfig.tcl 2012-06-06 13:59:56 UTC (rev 2009) @@ -270,6 +270,13 @@ set axis [list 0 [expr $channels-1] $channels] set axisspec [list $axis] + if {[array names parameters $module] eq ""} { + tk_messageBox -icon error -title {Missing parameters} \ + -message "Missing parameters array entry for $module" \ + -type ok + exit -1 + } + # The 1205 module is special because it creates 3 parameters # for each of the 16 channels... looking like a tree array per channel. # @@ -277,11 +284,9 @@ mapC1205Channels $id $moduleNumber $type $parameters($module) } else { - if {[array names parameters $module] ne ""} { - parammap -add $moduleNumber $type $id $parameters($module) - foreach parameter $parameters($module) { - spectrum $parameter 1 $parameter $axisspec - } + parammap -add $moduleNumber $type $id $parameters($module) + foreach parameter $parameters($module) { + spectrum $parameter 1 $parameter $axisspec } } incr moduleNumber Modified: branches/3.3-009-development/doc/Commands/treeparameter.htm =================================================================== --- branches/3.3-009-development/doc/Commands/treeparameter.htm 2012-05-18 17:49:41 UTC (rev 2008) +++ branches/3.3-009-development/doc/Commands/treeparameter.htm 2012-06-06 13:59:56 UTC (rev 2009) @@ -18,7 +18,7 @@ <a name="Top"> <h2>Syntax</h2></a> <pre> - treeparameter -create <i>name low high units</i> + treeparameter -create <i>name low high bins units</i> treeparameter -list [<i>pattern</i>] treeparameter -set <i>name bins low high inc units</i> treeparameter -setinc <i>name inc</i> @@ -194,7 +194,7 @@ <address><a href="mailto:fo...@ns...">Ron Fox</a></address> <!-- Created: Mon Apr 18 09:25:24 EDT 2005 --> <!-- hhmts start --> -Last modified: Thu Sep 22 13:51:15 EDT 2005 +Last modified: Wed May 30 07:47:21 EDT 2012 <!-- hhmts end --> </body> </html> Modified: branches/3.3-009-development/vmusb/Makefile.am =================================================================== --- branches/3.3-009-development/vmusb/Makefile.am 2012-05-18 17:49:41 UTC (rev 2008) +++ branches/3.3-009-development/vmusb/Makefile.am 2012-06-06 13:59:56 UTC (rev 2009) @@ -88,10 +88,25 @@ $(mkinstalldirs) @prefix@/TclLibs/vmusb $(INSTALL_DATA) spectclSetup.tcl configFile.tcl constants.tcl @prefix@/TclLibs/vmusb echo pkg_mkIndex -verbose @prefix@/TclLibs/vmusb "*.tcl" | $(TCLSH_CMD) + $(mkinstalldirs) @prefix@/share/vmusb + $(INSTALL_DATA) *.html @prefix@/share/vmusb + $(INSTALL_DATA) *.pdf @prefix@/share/vmusb + -for s in {1..8} ; do \ + $(mkinstalldirs) @prefix@/share/man/man$$s; \ + for f in *.$$s*; do \ + $(INSTALL_DATA) $$f @prefix@/share/man/man$$s; \ + done \ + done -EXTRA_DIST = MakefileSkel.in configFile.tcl spectclSetup.tcl CLLNLUnpacker.cpp +EXTRA_DIST = MakefileSkel.in configFile.tcl spectclSetup.tcl CLLNLUnpacker.cpp vmusb.xml -docs_built: \ No newline at end of file +docs_built: vmusb.xml + -$(MANDOCBOOK) man $< 2>/dev/null + $(HTMLDOCBOOK) $< + $(HCDOCBOOK) $< + dvipdf vmusb.dvi + touch docs_built + Added: branches/3.3-009-development/vmusb/vmusb.xml =================================================================== --- branches/3.3-009-development/vmusb/vmusb.xml (rev 0) +++ branches/3.3-009-development/vmusb/vmusb.xml 2012-06-06 13:59:56 UTC (rev 2009) @@ -0,0 +1,884 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd +" +> +<book> + <bookinfo> + <title>VMUSBSpecTcl</title> + <author><firstname>Ron</firstname><surname>Fox</surname></author> + <revhistory> + <revision> + <revnumber>1.0</revnumber> + <date>May 18, 1012</date> + <authorinitials>RF</authorinitials> + <revremark>Original Release</revremark> + </revision> + </revhistory> + </bookinfo> + <chapter> + <title>Introduction and background</title> + <para> + VMUSBSpecTcl is a tailored SpecTcl which has unpacking software + for all of the modules supported by the VMUSBReadout program. + By inserting a bit of metadata in the DAQ configuration file + used by VMUSBReadout, you can use VMUSBSpecTcl to analyze data + read by VMUSBReadout producing and produce raw spectra without + writing a single line of code. + </para> + <para> + The remainder of this manual has the following chapters: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis>VMUSBSpecTcl configuration</emphasis> describes + what you need to put in the daq configuration file to + make VMUSBSpecTcl create parameters and raw spectra for + each of the devices in your readout. + </para> + </listitem> + <listitem> + <para> + <emphasis>Extending VMUSBSpecTcl</emphasis> describes + how to extend the base VMUSBSpecTcl application. + At this poit in time emphasis is on how to add + additional event processors that interact with the raw, + unpacked parameters to produce computed parameters. + </para> + </listitem> + <listitem> + <para> + <emphasis>Running VMUSBSpecTcl</emphasis> describes what you need + to do to run VMUSBSpecTcl + </para> + </listitem> + <listitem> + <para> + <emphasis>Reference information</emphasis> provides manpage + like documntation to soem of the bits and pieces of + VMUSBSpecTcl that need it. + </para> + </listitem> + </itemizedlist> + + </chapter> + <chapter> + <title>VMUSBSpecTcl configuration</title> + <para> + VMUSBReadout uses a Tcl configuration file to define and configure + devices in the VME crate and to select the order in which they + are read out for each stack. + </para> + <para> + Normally one has a primary event stack and a scaler stack however, + the hardware, and software, support a total of 8 stacks with + differing trigger conditions including front panel, timed and + VME interrupts. + </para> + <para> + By adding a small amount of metadata to the configuration file, + the same information can be used by SpecTcl to select the order in + which it runs unpacking objects that understand the format of data + from each module, and distribute data from each channel into + parameters. Furthermore, once those raw parameters are known, the + SpecTcl configuration processing creates raw spectra for each + parameter that has been defined. + </para> + <para> + The primary bit of metadata required by VMUSBSpecTcl is Tcl array + named <varname>adcParameters</varname>. This array is indexed by + module name and each element contains a list of the parameter names + to be associated with the input channels of the digitizer. + If a channel is unused, use an empty string (<literal>""</literal>). + If the last several channels are unused you can just supply a shorter + list. + </para> + <para> + The remainder of this chapter are a set of examples that + show how you can define the parameters of a CAEN V785 peak + sensing ADC module you have named <literal>adc</literal>. + The first example shows how to use a Tcl loop to define + parameters named <literal>adc.00</literal> through + <literal>adc.31</literal>. The Tcl + <command>format</command> command is used to ensure that + the channel number has leading zeroes if needed. + <command>lappend</command> (list append) + is used to construct the list an element + at a time each pass through the loop. + </para> + <example> + <title>Using a loop to create parameters</title> + <programlisting> +for {set i 0} {$i < 32} {incr i} { + lappend adcParameters(adc) [format adc.%02d $i] +} + </programlisting> + </example> + <para> + The next example equivalent to the previous one but much more + work to write. Something like this may be needed, however if your + parameter names don't occur in sets with some regular pattern + (remember that you could have several for or foreach loops all + lappending to the same <varname>adcParameters</varname> element). + </para> + <example> + <title>Creating parameter names the long way</title> + <programlisting> +set adcParameters(adc) [list adc.00 adc.01 adc.02 adc.03 adc.04 \ + adc.05 adc.06 adc.07 adc.08 adc.09 \ + adc.10 adc.11 adc.12 adc.13 adc.14 \ + adc.15 adc.16 adc.17 adc.18 adc.19 \ + adc.20 adc.21 adc.22 adc.23 adc.24 \ + adc.25 adc.26 adc.27 adc.28 adc.29 \ + adc.30 adc.31 \ + ] + </programlisting> + </example> + <para> + The next example shows how to declare define the same ADC, if you + are not using channels 5 through 9. + </para> + <example> + <title>Unused parameters in the middle</title> + <programlisting> +set adcParameters(adc) [list adc.00 adc.01 adc.02 adc.03 adc.04 \ + "" "" "" "" "" \ + adc.10 adc.11 adc.12 adc.13 adc.14 \ + adc.15 adc.16 adc.17 adc.18 adc.19 \ + adc.20 adc.21 adc.22 adc.23 adc.24 \ + adc.25 adc.26 adc.27 adc.28 adc.29 \ + adc.30 adc.31 \ + ] + </programlisting> + </example> + <para> + Finally, if you are only using the first 8 channels of the + ADC (channels 0-7): + </para> + <example> + <title>Onl using the first few channels</title> + <programlisting> +for {set i 0} {$i < 8} {incr i} { + lappend adcParameters(adc) [format adc.%02d $i] +} + </programlisting> + </example> + </chapter> + <chapter> + <title>Extending VMUSBSpecTcl</title> + <para> + In this chapter we will learn how to extend VMUSBSpecTcl by adding + event processors that produce computed parameters from existing + raw parameters prepared for us by the VMUSBSpecTcl raw event processor. + The specific learning objectives are: + </para> + <itemizedlist> + <listitem> + <para> + Learn how to get a copy of the VMUSBSpecTcl skeleton. + </para> + </listitem> + <listitem> + <para> + Learn how to locate and reference parameters by name using the + Spectcl API. + </para> + </listitem> + <listitem> + <para> + Learn how to create a Tree parameter proxy for a named + parameter. + </para> + </listitem> + <listitem> + <para> + Learn how to integrate our changes with the skelton. + </para> + </listitem> + </itemizedlist> + <formalpara> + <title>Copying the VMUSBSpecTcl skeleton</title> + <para> + The VMUSBSpecTcl skeleton is located in + <filename>$SpecTclHome/VMUSBSkel</filename> where + <literal>$SpecTclHome</literal> is the top level directory + of your SpecTcl installation. For version 3.3 at the + NSCL, this is <filename>/usr/opt/spectcl/3.3/VMUSBSkel</filename>. + <footnote> + <para>VMUSB support first appears in version + 3.3-009. Be sure your SpecTcl version is at least this + high before looking. + </para></footnote> + </para> + </formalpara> + <para> + If The following sequence of commands creates an empty directory + and copies the skeleton files into it from + <filename>/usr/opt/spectcl/3.3/VMUSBSkel</filename>: + </para> + <example> + <title>Copying the skeleton files</title> + <programlisting> +mkdir myspectcl +cp /usr/opt/spectcl/3.3/VMUSBSkel/* myspectcl + </programlisting> + </example> + <para> + The resulting <filename>myspectcl</filename> directory contains + all the files needed to build a new copy of + VMUSBSpecTcl and a <filename>Makefile</filename> that actually + does that. Since this is just a tailored SpecTcl, you can + add event processors in the normal way, by writing an + event processor and registering an instance of it as an event + processor in <methodname>CreateAnalysisPipeline</methodname>. + </para> + <formalpara> + <title>Using the SpecTcl API to locate parameters by name</title> + <para> + If you are writing event processors that create computed parameters, + you will quickly run into the need to located parameters by name. + </para> + </formalpara> + <para> + Specifically, you need to determine if a parameter has been defined by + the VMUSB unpackers and you need to fetch its value if it has been. + You may also wish to locate your own parameters by name so that you + give them values for an event. + </para> + <para> + The example below shows + an event processor method that looks up two parameters and stores + their parameter ids in member data of the object. The parameter id + is the parameter's index into the <parameter>rEvent</parameter> pseudo array + passed to the event processor's <methodname>operator()</methodname> + method. + </para> + <example> + <title>Using the SpecTcl API to locate parameters</title> + <para> + In the code below, we assume that + <varname>m_param1, m_param2</varname> and + <varname>m_initialized</varname> are two integer variables + and a <type>bool</type> respectively. We also assume that + <varname>m_initialized</varname> is set to <literal>false</literal> + when our event processor is constructed. + </para> + <programlisting> +#include <SpecTcl.h> +#include <Parameter.h> +#include <string> +... + +//do the actual lookup: + +void CMyUnpacker::lookupVariables() +{ + if (!m_initialized) { + SpecTcl *pApi = SpecTcl::getInstance(); <co id='apilookup-instantiate' /> + + CParameter* p1 = pApi->findParameter("param1"); <co id='apilookup-p1' /> + if (!p1) { + throw std::string("Could not find param1"); <co id='apilookup-error' /> + } + m_param1 = p1->getNumber(); <co id='apilookup-getid' /> + + CParameter* p2 = pApi->findParameter("param2"); <co id='apilookup-p2' /> + if (!p2) { + throw std::string("Could not find param2"); + } + m_param2 = p2->getNumber(); + + m_initialized = true; + } +} + </programlisting> + </example> + <calloutlist> + <callout arearefs='apilookup-instantiate'> + <para> + Creates an instance of the SpecTcl API object. This object + contains data and methods that make up the SpecTcl API. + </para> + </callout> + <callout arearefs='apilookup-p1'> + <para> + <methodname>findParameter</methodname> locates the parameter + object (<type>CParameter</type>) that is associated with a parameter + given its name. A pointer to the parameter object is returned + if the parameter is found. If the parameter does not exist, + <literal>NULL</literal> is returned. + </para> + </callout> + <callout arearefs='apilookup-error' > + <para> + In this example, if the named parameter is not found, + a <type>std::string</type> exception is thrown. You + must either arrange for the exception to be caught or rely on + some SpecTcl last chance exception handler. If this is called + from an event processor's <methodname>operator()</methodname> + method, the event processing framework will report the message + and abort further processing of the event. + </para> + </callout> + <callout arearefs='apilookup-getid'> + <para> + The <methodname>getNumber</methodname> method of a parameter object + returns the id of the parameter. The id of the parameter is + a unique number that identifies the parameter. It is als the + index into the <parameter>rEvent</parameter> array passed to the + <methodname>operator()</methodname> method of an event processor + class. + </para> + </callout> + <callout arearefs='apilookup-p2'> + <para> + Similarly, the code looks up the parameter id of the parameter + <literal>param2</literal> by locating its <classname>CParameter</classname> + object and asking it to return the parameter id via + <methodname>getNumber</methodname>. + </para> + </callout> + + </calloutlist> + + <para> + Once this code has executed it sets the <varname>m_initialized</varname> + member data to <literal>true</literal> so that it only executes once. + Since parameter definitions tend to change only by recompiling SpecTcl, + this method is quite safe and has no time impact on event processing. + </para> + <para> + If you are used to using Tree parameters, you can make use of the + fact that tree parameter and treeparamter array objects can bind themselves + to their parameters and then be treated as if they were the parameters + themselves. + </para> + <para> + The next example assumes you have the same parameters, <literal>param1</literal> + and <literal>param2</literal> but that instead of declaring integer + members you have declared <classname>CTreeParameter</classname> members + named <varname>m_param1</varname> and <varname>m_param2</varname>. + Our example will not show how to associate limits, default-binning and + units with the parameter, however different overloads of the + <methodname>Initialize</methodname> method can do that if you need that. + </para> + <example> + <title>Binding Tree Parameters to existing parameters</title> + <programlisting> +#include <TreeParameter.h> +... +void CMyUnpacker::lookupVariables() +{ + if (!m_initialized) { + m_param1.Initialize("param1"); <co id='tree_init1' /> + m_param1.Bind(); <co id='tree_bind1' /> + + m_param2.Initialize("param2"); <co id='tree_2' /> + m_param2.Bind(); + m_initialized = true; + } + +} + </programlisting> + </example> + <calloutlist> + <callout arearefs='tree_init1'> + <para> + A tree parameter declared as + <programlisting> +<classname>CTreeParameter</classname> <varname> m_param1</varname>; + </programlisting> + e.g. is said to be uninitialized. Minimally, this parameter + must be initialized with the Spectcl parameter name it + will be used for and bound to that parameter. + </para> + <para> + This line initializes the tree parameter so that it will + be bound to the parameter <literal>param1</literal>. + </para> + </callout> + <callout arearefs='tree_bind1'> + <para> + Binds the parameter. This looks up the parameter and + stores the parameter id within the tree parameter object so that + SpecTcl can know which <literal>rEvent</literal> + element the tree parameter + represents, and make that association prior to processing each + event. + </para> + </callout> + <callout arearefs='tree_2'> + <para> + The procedure for initializing and binding <varname>m_param2</varname> + is identical to that of <varname>m_param2</varname> + </para> + </callout> + </calloutlist> + <formalpara> + <title>Integrating changes with SpecTcl</title> + <para> + The key to VMUSBSpecTcl integration is that it's just SpecTcl. + Edit the Makefile and add your event processor files to the + definition of the <literal>OBJECTS</literal> macro just like you + would for any other SpecTcl and use <command>make</command> + to build your SpecTcl. + </para> + </formalpara> + <para> + If you want to keep your objects separate from the standard + VMUSBSpecTcl objects you could also do a two levels scheme like + the one shown below. + </para> + <informalexample> + <programlisting> + +USEROBJECTS=MyEventProcessor.o + +OBJECTS=MySpecTclApp.o ParamMapCommand.o CCUSBUnpacker.o \ + CCCUSBPacket.o CPh7xxUnpacker.o CFixedSizedUnpacker.o \ + CC1205Unpacker.o $(USEROBJECTS) + + </programlisting> + </informalexample> + <para> + In this scheme you add your objects to a new macro + <literal>USEROBJECTS</literal> which is invoked at the end of + <literal>OBJECTS</literal>. + </para> + </chapter> + <chapter> + <title>Running VMUSBSpecTcl</title> + <para> + Beginning with SpecTcl version 3.3-009 VMUSBSpecTcl is installed + in the <filename>bin</filename> directory of the SpecTcl installation + tree. If you don't need to modify it, you can run it directly + from that location. + </para> + <para> + VMUSBSpecTcl is run just like any other SpecTcl. Some additions + to your <filename>SpecTclRC.tcl</filename> file are required + to load and process your desired configuration file. + The Tcl code fragment below shows how to do this: + </para> + <informalexample> + <programlisting> +## +# Configure the VM-USB unpacker software: +# +# You should probably change the code below to +# load the configuration file of your choice. +# + +set daqconfig [file join ~ config daqconfig.tcl]; # default config file. + +lappend auto_path [file join $SpecTclHome TclLibs] +package require vmusbsetup + +vmusbConfig $daqconfig + + </programlisting> + </informalexample> + <para> + This example unconditionally uses + <filename>~/config/daqconfig.tcl</filename> as the configuration filename. + You should probably substitute some other mechanism. Two that I have used + are to + <orderedlist> + <listitem> + <para> + Remove the definition of daqconfig above and put it + in <filename>SpecTclInit.tcl</filename> then you can + select a configuration file by editing the relatively short + <filename>SpecTclInit.tcl</filename> file. + </para> + </listitem> + <listitem> + <para> + Set <varname>daqconfig</varname> from a call to + <command>tk_getOpenfile</command>. <command>tk_getOpenFile</command> + is a Tk utility that opens a file chooser dialog and + returns the path to the file chosen from that + dialog. + <ulink url='http://www.tcl.tk/man/tcl8.5/TkCmd/getOpenFile.htm' /> + describes this command and gives an example of its use. + </para> + </listitem> + </orderedlist> + </para> + <para> + To summarize, the key points are that your + <filename>SpecTclRC.tcl</filename> file should + </para> + <itemizedlist> + <listitem> + <para> + Figure out the name of the configuration file you + want to use. + </para> + </listitem> + <listitem> + <para> + Add the SpecTcl Tcl package library directory to the + <varname>auto_path</varname>. + </para> + </listitem> + <listitem> + <para> + Load the <literal>vmusbsetup</literal> package via + <command>package require</command> + </para> + </listitem> + <listitem> + <para> + Invoke the <command>vmusbConfig</command> command passing + it the name of your configuration file. + </para> + </listitem> + </itemizedlist> + </chapter> + <chapter> + <title>Reference information</title> + <para> + This section provides reference information. It is also used to + generate manpages for the SpecTcl installation. The man pages + are installed in <filename>$SpecTclHome/share/man</filename> + where <varname>SpecTclHome</varname> is the top level of the + SpecTcl 3.3 installation tree. You can view these man pages by + adding the <option>-M $SpecTclHome/share/man</option> option to the + <command>man</command> command. + </para> + <refentry id="vmusb_configfileman"> + <refmeta> + <refentrytitle>VMUSB SpecTcl metadata</refentrytitle> + <manvolnum>5vmusbSpecTcl</manvolnum> + </refmeta> + <refnamediv> + <refname>Config File</refname> + <refpurpose>VMUSBSpecTcl metadata.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command> +set adcChannels(<replaceable>moduleName</replaceable>) <replaceable>channel-list</replaceable> + </command> + </cmdsynopsis> + + </refsynopsisdiv> + <refsect1> + <title>DESCRIPTION</title> + <para> + The <varname>adcChannels</varname> array is indexed by + VMUSB module names and defines the name of SpecTcl parameters + into which each module's data will be decoded. + </para> + <para> + For most simple modules, the value of an + <varname>adcChannels</varname> element is just the parameter + names for each channel of that module. See SPECIAL CASES + below for exceptions. + </para> + <para> + Unused trailing channels can be omitted from the list. By + convention, channels that are given the name "" are not + used as well. This allows you to have sparsely populated + modules with either trailing unused channels or a set of unused + channels in the middle of the module channel list. + </para> + </refsect1> + <refsect1> + <title> + SPECIAL CASES + </title> + <para> + Some modules do not fit the model described above in + DESCRIPTION. For these modules, the <varname>adcParameters</varname> + array element is still used, however it may be interpreted + differently or even coupled with additional metadata. + </para> + <refsect2> + <title>CAEN Dual range ADC's</title> + <para> + The CAEN V956 is a dual range QDC. Each input channel + produces a high and a low gain output. This allows the + QDC to have good resolution at both the high and low + end of the input range. + </para> + <para> + In the CAEN V956, rather than requiring the user to + specify each paramter, the value of the parameter list are + taken as base parameter names and a + <replaceable>base-name</replaceable><literal>.l></literal> and + <replaceable>base-name</replaceable><literal>.h</literal> paramter and spectrum + are produced for each. Where <literal>.l</literal> means + low range and <literal>.h</literal> means high range. + full resolution Spectra are produced for both of these parameters. + </para> + </refsect2> + <refsect2> + <title>Washington University HINP chip readout FPGAs</title> + <note> + <title>NOTE</title> + <para> + Support for the WUSTL HINP chip readout and analysis + was provided by Jon Elson at Washington Univ. + </para> + </note> + <para> + Washington University in St. Louis have built front end + ASIC based boards that are designed for detector arrays + with a large number of channels. + The HINP board described in + <ulink url='http://www.chemistry.wustl.edu/~lgs/NIMA_573_418_2007.pdf' /> + use a discriminator and sample and hold array to + sparsify and hold peak voltages and timing information + from the detector array. + </para> + <para> + The preferred way to acquire data from these boards is + via a JTEC XLM-XXV which where the custom firmware in the + FPGA sequences analog data through that modules FADC + and merges it with the corresponding timing data. + </para> + <para> + Since essentially arbitrarily sized arrays can be managed + with this electronics, additional metadata is required. + Specifically, one needs to know the number of HINP chips + in the configuration. This information is stored in the + array <varname>HINPChips</varname> which is indexed by module + name. Each element of this map is a list of the chip + address numbgers of the chips that are being read out. + </para> + <para> + The <varname>adcChannels</varname> array element is a base + name for the entire chipset. From this base name parameters + are constructed for the energy and times of all channels + of all chips as follows: + <replaceable>base-name</replaceable>.<replaceable>chip-address.nn</replaceable>.<literal>e</literal> + and + <replaceable>base-name</replaceable>.<replaceable>chip-address</replaceable>.<literal>t</literal> + where <replaceable>base-name</replaceable> is the base parameter + name from <varname>adcChannels</varname>, + <replaceable>chip-address</replaceable> is a two digit + decimal chip address from <varname>HINPChips</varname> + and <replaceable>nn</replaceable> a two digit channel number + from within the chip in the range <literal>[00 .. 15]</literal>. + </para> + <para> + Full resolution spectra are created for each of these + parameters. + </para> + </refsect2> + <refsect2> + <title>Washington University PSD chip readout FPGAs</title> + <note> + <title>NOTE</title> + <para> + Support for the WUSTL PSD chip readout and analysis + was provided by Jon Elson at Washington Univ. + </para> + </note> + + <para> + Washington University in St. Louis has built a + set of front end board for large detector arrays. + The board are populated with a set of ASIC chip boards. + Each ASIC is capabile of performing charge integration + over three regions of the pulse. + See + <ulink url="http://www.sciencedirect.com/science/article/pii/S0168900209019639" /> + for information about this system, althought the + channel density has been increased to 16 channels/chip + since that article was published. + </para> + <para> + The analog are sparsified and held in the ASIC + along with timing information for the non-zero + channels. The preferred way to read data from + from the PSD chips is with a JTEC XLM-XXV. + </para> + <para> + Custom firmware in the XLM's FPGA sequences analog + data to the FADC on the XLM-XXV and combines it with + the digital timing information for each non-zero + channel. + </para> + <para> + Since arbitrary sized arrays can be handled by + this system, the <varname>adcChannels</varname> + variable only supplies a parameter base name. + Additional metadata is required to describe the + size of the system. + </para> + <para> + <varname>PSDChips</varname> + is an array that is indexed by module name and + contains a list of the chip addresses that are in + use by the system. Each chip is capable of + handling 16 channels. Therefore, the base name + and chip addresses are used to create parameter names + of the form: + <replaceable>base-name</replaceable>.abct.<replaceable>chip-address</replaceable>.<replaceable>nn</replaceable> + Where; <replaceable>base-name</replaceable> is the + value in <varname>adcParameters</varname> for the module, + <literal>abct</literal> is one of a,b,c,t where + a,b,c represent an integrationintervale and t the time + parameter. <replaceable>chip-address</replaceable> is the + address of the chip and <replaceable>nn</replaceable> the + two digit channel number within the chip from + <literal>[0..15]</literal>. + </para> + </refsect2> + <refsect2> + <title>Indiana University MASE chip readout FPGAs</title> + <para> + The Indiana University MASE chip readout is a hieararchical + readout system intended for highly segmented silicon + detector arrays. It is described in + <ulink url='http://www.sciencedirect.com/science/article/pii/S0168900206016664' />. + </para> + <para> + In summary, the system consists of a number + of Controller boards (COBs). A number of + Channel boards (CHB) connect to these COBs. + Each channel board can manage 16 channels. + The entire system i scapable of reading + over 4000 channels of Si detector. The entire system + is read using an FPGA base XLM module. + </para> + <para> + In addition to <varname>adcChannels</varname> the + MASE requires two piecs of additional metadata. + <varname>maseCOBCount</varname> is an array indexed + by module name that contains the number of COB boards + in the system. the array <varname>maseCHBCounts</varname> + further provides a list of the number of CHB modules + attached to each COB. This allows for COBs that are not + fully populated. CHB addresses are always sequential + and start from zero as are COB adresses. + </para> + <para> + As the MASE system only produces energy information, + this results in parameters and full resolution spectra + of with names of the form: + <replaceable>base-name</replaceable>.<replaceable>cob</replaceable>.<replaceable>chb</replaceable>.<replaceable>chan</replaceable> + Where <replaceable>base-name</replaceable> is the + base name of the parameter in <varname>adcChannels</varname>, + <replaceable>cob</replaceable> is the COB board + address as a two digit decimal number, + <replaceable>chb</replaceable> is the CHB board + address as a two digit decimal number and + <replaceable>chan</replaceable> is a two digit + channel number within the CHB. + </para> + </refsect2> + <refsect2> + <title>CAEN V977 I/O register</title> + <para> + The CAEN V977 operates like a 'normal' one channel + module except that the spectrum it generates is + a 16bit bitmask spectrum. + </para> + </refsect2> + <refsect2> + <title>CAEN V 1x90 multi-hit TDCs</title> + <para> + The CAEN V 1x90 TDC family (V 1190 and V1290) are + multihit TDCs that have settablechannel ranges. + The configuration parameters also make it possible + to know the timescale of the spectra created for this + module. Furthermore, since the module gate is clocked in + by the TDC timing relative to that gate is much worse + than the TDC is capabile. Therefore the software supports + doing a digital subtraction from the digitized time of the + gate (a reference channel). + </para> + <para> + The additional metadata for this module is therefore + the values of the following options: + </para> + <variablelist> + <varlistentry> + <term><option>-depth</option></term> + <listitem> + <para> + Determines the number of hits that will + be histogrammed. The software will + create one histogram per channel per allowed hit. + Names of the parameters/histograms + are of the form <replaceable>name</replaceable>.<replaceable>n</replaceable> + where <replaceable>name</replaceable> was the + name for the channel in <varname>adcChannels</varname> + and <replaceable>n</replaceable> is the + hit number from zero. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-refchannel</option></term> + <listitem> + <para> + Set the channel number that will be used + as the gate time channel. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-channelcount</option></term> + <listitem> + <para> + The V1x90 is a familly of TDCs with many + different options for channel count. + This value determines the number of + channels to expect. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-window</option></term> + <listitem> + <para> + Determines the full scale range of the TDC + by setting the width of the digitized time + window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-offset</option></term> + <listitem> + <para> + Determines where the window starts relative to the + gate and therefore establishes the time at the + left end of the spectrum. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-edgeresolution</option></term> + <listitem> + <para> + Determines the width in time of each + channel of the spectrum. Together with + <option>-window</option> this also + determines the number of channels + in each spectrum. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Note that setting all but <option>-channelcountM</option>, + <option>-refchannel</option> and <option>-depth</option> + affect the way the TDC operates and you should keep + your application in mind when doing so. + </para> + </refsect2> + </refsect1> + + </refentry> + + + </chapter> +</book> \ No newline at end of file This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |