Since electromagnetic showers are simulated through calls to the subroutine SHOWER of the EGS package, many of the conventions of that program are adopted by UMC. Individuals not already familiar with EGS are encouraged to read, at least in part, the EGS manual as this will help in the understanding of the UMC code.

DECAYS

DETECTOR_VERSIONS

The various detector subsystems typically come in different versions. The user controls which version of each by using the IxxVER parameters in conpar.cmn (See CONPAR). In each case, IxxVER = 0 is the original (old) version and IxxVER = 1 is the new, 1994+, version. Though it will probably not be particularly useful, almost any mix of new and old versions is possible. One exception: the new and old trigger each assume specific versions of certain subsystems. AS OF JANUARY 1996, THE 1995 DETECTOR CONFIGURATION IS THE DEFAULT. See $UMC_COM/1991.par for the parameter file necessary to convert to the 1991 detector. In this section, we include various notes pertaining to specific subsystem versions.

Additional Information on:

in $UMC_DIR:

umctrig.cdf -- This file contains a template for the user code needed for a typical application (see USER_ROUTINES). Since triggering and tapewriting are called from user code, most users will copy umctrig.cdf to their own area and edit it to begin development of an application code.

in $UMC_COM:

Makefile -- Sample Makefile to create a UMC executable.

umc.sh -- This file runs the executable module produced by Makefile, after making the necessary environment variable assignments.

generic* -- Executed by umc.sh for year-specific assignments

1991.par -- Parameter file to change the spectrometer from the 1995 configuration (the default) to the pre-92 configuration. This should be copied into all .par files for this era.

sample.par -- A simple example of a basic parameter file

The user will most likely want to copy some of these files into his or her own directory to permit modification to a particular application.

Additional Information on:

Additional Information on:

Although the EGS package does not include a version of HOWFAR ( i.e. it is a user subroutine), a standard set of HOWFAR routines specifying the E787 geometry is included with the UMC package. HOWFAR can be called by EGS, STEP (the routine used for the tracking of non-showering particles), or directly from user code. As a consequence, any geometry changes are automatically incorporated into all parts of the program.

Additional Information on:

The recent (1/96) update of UMC V5 contains a new method of starting Kaons using beam files generated from data. The modifications are in ustart.cdf. As with the old methods, the new method starts with (x,y,z) of the K stop from Kmu2 events. However, this information is used differently, and there is additional information in the beam file $BM_STOP.

Briefly, The new K starting method is to start the K at rest at its actual stop position. For the K target hits, the real K hits from the event are stored in the beam file and loaded directly into the appropriate arrays. The same can be done with accidental hits, also stored on the file.

IBMMOD =

0: UMC beam (default)......No beam file used. Starts K at front of degrader with momentum and direction determined by parameters in CONPAR. Stopping z controlled by adjusting P0BEAM.

1: Real x, y...............Old beam file. Use only X and Y, with Z chosen randomly from a gaussian distribution with mean and sigma from data statement. Then pull K back 50 MeV and let it go.

2: Real x, y, z............Old beam file. Use X, Y, and Z. Then pull K back 50 MeV and let it go. (Standard mode for '89-'91 analyses.)

3: Real x, y, z............New beam file. Use X, Y, and Z. Then pull K back 50 MeV and let it go. (Same as mode 2, but use new beam file.)

4: Real x, y, z, K hits....New beam file. Use X, Y, and Z. K started at this location AT REST. Real K hits loaded directly into appropriate arrays.

5: Real x,y,z, K&acc hits..New beam file. Use X, Y, and Z. K started at this location AT REST. Real K hits loaded directly into appropriate arrays. The accidental hits are also loaded into the appropriate arrays; a fake "neutron" is used to store the accidental info in the track bank.

-n: disable radial weight..For modes 1-5, a weight is applied to the x,y hit to undo the bias in the radial distribution measured in Kmu2's due to the requirements of the trigger. (This shape is hard-wired in FUNCTION WGHT at the end of this file.) For mode n, setting IBMMOD = -n will DISABLE the weighting. WARNING: IBMMOD set to |IBMMOD| on first call. NOTE: this mode is for debugging only.

Note that mode 3 is the same as old mode 2.

-- It is expected that modes 4 and 5 will be the standard ones. IBMMOD = 0 is also useful for simple tasks. IBMMOD<0 is for debugging only. IBMMOD = 1 and 2 are obsolete. Beam files for those modes exist only for 1989-91 data.

-- ${UMC_COM}/generic_95.sh will automatically point to an appropriate $BM_STOP file.

-- The current beam file $UMC_DATA/kstop_95.20.dat comes from skimmed monitor tape Kmu2(1).20. It contains 22k events with a typical intensity of 1.2M KB/spill. I will eventually generate a prescaled file covering the whole run.

-- I have also generated a beam file for Mark Convery's low intensity running in 1994.

Additional Information on:

Through the years, this connection weakened for several reasons. As more and more parts of the apparatus were added to PHOTO, the software authors simply coded up geometrical descriptions directly for KOFIA. This wasn't a bad thing -- for many of these systems (RSPC, TG, etc.), the UMC geometrical representation was only approximate anyway. Also, as the drawing routines became more elaborate, they were copied from UMC to KOFIA and modified there.

This has been changed. One no longer links UMC when making a KOFIA PHOTO executable. Instead, PHOTO routines read in files generated by special runs of UMC.

-- The BV and RD geometries are still calculated by UMC. This retains their definitive nature and their full 3-d representation of the detector. UMC is run once to generate geometry files. This facility is activated simply by defining environment variables UMC_GEOMxx with xx=BV or RD for the barrel or new range stack. The modified UMC routines will be in UMC V5 when next updated, but are not needed by the users because all the files have already been generated and installed.

-- The subsystems in the old detector that used UMC geometry (RS, EC, DC) are also handled by making geometry files with UMC. One generates the old files by simply setting up the old detector in UMC and running with the appropriate environment variables defined. Again, the files have already been created. Amazingly enough, KOFIA 2.0 still seems to work with 1991 data, at least in PHOTO.

-- These files are located in $CAL_DB, but are NOT installed in CFM as they are not run-dependent. The routines DRAWxx read in the files using the environment variable $CAL_DB and a hard-wired filename (xx_geo.nnnnn). Since the new and old detector versions are drawn by different routines (RD and RS, E2 and EC, DC and UT), the filenames do not need changing.

Geometry files in $CAL_DB: bv_geo.00095, dc_geo.00091, ec_geo.00091, rd_geo.00095, rs_geo.00091

USER_INTERFACE

COMMON_BLOCKS

INCLUDE 'UMC$DIR:TRKBNK.CMN'

To avoid variable name conflicts, the *.CMN files have been written to be compatible with the VAX FORTRAN "IMPLICIT NONE" feature (see VAX/VMS FORTRAN manual for further details). In particular, this means that each variable and array in a COMMON block is explicitly "typed" in the *.CMN file. Users are encouraged, but not required, to take advantage of the IMPLICIT NONE feature in their user codes.

Additional Information on:

The physics of NUCINT is described in E787 Tech. Note 140. A stand-alone version of NUCINT is described in E787 Tech. Note 141. This note describes access to NUCINT from UMC.

Normally NUCINT is "on". If the user wishes to turn NUCINT "off", the following must appear in the NUCINT input stream:

NICNTL/1/

Only very limited user interaction with NUCINT is available at the present time. The primary interaction is thru the following common block:

COMMON/NIINFO/NIERR,NISOVF,NIREAC,NITYPE(5),NIREGN(5)

NIERR is the total number of errors encountered by NUCINT during the course of a run - see Tech. Note 141. NISOVF is the number of times the UMC stack overflowed during the course of a run. The user should print these at the end of her/his run (in UEND) if she/he wishes to be cautious. The remaining variables are accumulated thru an event and may be examined in the user routine UEVENT. NIREAC is the total number of interactions in the event, NITYPE(I) is the type (see both Tech. Notes) of the Ith reaction and NIREGN(I) is the region number of the Ith reaction.

The user may also wish to obtain additional information from NUCINT as described in Tech. Note 141. As described in that note, NUCINT has energy cut-offs; particles below the cut-offs are not put on the "created particle" stack. In UMC, these cut-offs are 2 MeV for photons, 14 Mev for protons, and 8 MeV for neutrons. The user may adjust these as described in Tech. Note 141.

USER_ROUTINES

A number of USER routines are called by the program. The USER may wish to provide her own version of some or all of them. Their intended functions are described below. An example file umctrig.cdf is provided that contains model versions of UEVENT and UEND, as well as dummy versions of UAUS and UINIT. Most applications will begin by copying umctrig.cdf and editing it. Most applications use the default USTART.

Additional Information on:

Additional Information on:

Additional Information on:

Additional Information on:

Type Common block Example

I/O IOPAR ILP = line printer unit number

Control & physics CONPAR KDKMOD = type of K decay requested

Geometry GEOPAR TSCNRS = thickness of scintillator in RS

Trigger TRGPAR WIDTHK = width of KB pulse

All parameters have defaults that will give reasonable running conditions. The values of all parameters are printed at the beginning of the output of a UMC run.

Additional Information on:

CONPAR

GEOPAR

Additional Information on:

MEDIA

The available media are listed in alldat.cdf.

RANDOM_NUMBERS

INSEED = 9 ==> seeds are environment variables UMC_SEED1 and UMC_SEED2. Example: in your shellscript:

setenv UMC_SEED1 10101 ! sets NSEED1=10101

setenv UMC_SEED2 22211 ! sets NSEED2=22211

INSEED >=0(but not 9) ==> Start RANMAR with seeds NSEED1,2

NSEED1 and 2 are parameters. 0 <= NSEED1 <= 31328, 0 <= NSEED2 <= 30081

Additional Information on:

Instant Replay -- for debugging, the user can set IREP = 1. This will cause the previous event to be created again, with all the print flags set by the user activated (even though IEV<IEVDMP). This is useful: rare problems can be caught after the fact, say in UEVENT, but detailed diagnostic info still can be printed. NOTE: the user MUST set IREP back to zero after the replay and it is her responsibility to avoid double-counting in histograms, etc.

Example:

In .par:

'IDUMPU' 1111011 / ! Evt and target display, TD arrays

'IEVDMP' 9999999 / ! Don't dump normal events

'NDUMP' 5 / ! Dump up to 5 repeated events

In uevent.cdf:

IF(IREP .EQ. 0)THEN C HISTOGRAMS HERE IF(ENERGY .LT. 0.)THEN WRITE(ILP,*) ' OOPS -- E .LT. 0 -- REPLAY EVENT ', IEV IREP = 1 RETURN ENDIF ELSE IREP = 0 ENDIF

Replay/restart after end of run or crash -- UMC can be started from the file created by the random number generator at the end of each successfully-generated event. (At some times we have had this file written every 10 events.) Setting parameter INSEED<0 (see CONPAR INSEED) will start UMC with the random number seeds stored in the file assigned to $SEED_DATA. This file also contains the record number in the beam file $BM_STOP used for this event, and the event number. This is useful for debugging after a crash, as the same event can be generated. NOTE: as currently set up, the events will start with the event number in $SEED_DATA. This can screw up things like the print limits on the event dumping and, most notably, NEVENT, the number of requested events. So, if you use this to run a chain of 100k-event runs, each starting where the previous one left off, the second run will exceed the event limit on the first event.

TRANSIENT_DIGITIZER_DATA

For each counter, the deposited energy is kept track of in 1 ns time bins. These energies are accessed by (ISYS, I1, I2, IEND), where:

ISYS = subsystem number = 2 for TG 4 for RS 5 for BV 6 or 7 for EITHER EC.

I1,I2 = local counter indices = IX (1-20), IY (1-20) for TG layer (1-21), sector (1-24) for RS layer (1-4), sector (1-48) for BV phi (1-24), cap (1-2) for EC

IEND = 0, -1, +1 for sum, -z end, +z end for RS and BV 0 only for TG and EC

To PUT an energy deposition EDEP at a time TIME into the TD arrays:

CALL TDPUT( EDEP, TIME, ISYS, I1, I2, IEND ).

The energy depositions of the standard UMC are already entered into the TD arrays via AUSGTG, AUSGRS, AUSGBV, and AUSGEC. The User does not have to do it.

To GET BACK the data for a counter from the TD arrays:

REAL ETD(100), TTD(100) INTEGER NTD ... CALL TDGET( ISYS, I1, I2, IEND, NTD, ETD, TTD ).

This routine returns: NTD = the number of hits (will be less than 101). ETD(i) = the energy of hit i. TTD(i) = the time of hit i. The hits are in time order. Recall that the data is binned in time, so all energy depositions within a 1 ns bin are coalesced. For an example of the use of the TD data, see the listing of SUBROUTINE EVTDMP. To CLEAR the TD arrays:

CALL TDCLR.

This is already done in EVTCLR. The User does not have to do it.

To get a dump of the transient digitizer data of an event, set the appropriate bits in the parameter IDUMPU (see HELP UMC IOPAR IDUMP).

Logicals

The UMC system makes frequent use of logical directory names. This is done to ease the problems of transporting the code from machine to machine.

Additional Information on:

The scheme we plan to adopt is as follows:

1) The "original" version of the code will be kept in a directory PUPHEP::[E787.UMC.V1]. Once the code has been transmitted to other sites (expected around 6/88 )this directory will be frozen -- i.e., no write access will be allowed. It is recommended that the contact people at other sites create an identical "read-only" directory.

2) Updates originating at Princeton, will be made by placing modified versions (after careful testing in working directories ) of the affected codes in a new subdirectory PUPHEP::[E787.UMC.V2.1]. Users at Princeton will be encouraged to include these codes in any new, and where appropriate, ongoing projects. Updates originating at other sites can be added to similar subdirectories locally. The authors of such changes are encouraged to notify either Dan Marlow or Peter Meyers of their updates so that they can be included in the central version at Princeton.

3) At intervals dependent on the number and nature of the changes, updates from all three institutions will be integrated, a new standardized version will be distributed to all sites, and the Princeton version will be frozen. At this point, the code at all institutions should once again be identical. The process of integrating the changes from different places may require the creation of a new sub-version at Princeton, moreover, more than one sub-version may have been generated at other institutions, thus the first newly distributed version number will not necessarily be UMC.V2.1.

4) There is at least one additional complication which arises from the use of INCLUDE statements in the FORTRAN. If a change requires that a COMMON block be modified, then it will be necessary to recompile all modules using that block. Since the COMMON blocks are placed in the code through the use of statements of the form " INCLUDE 'UMC$DIR:blockname.CMN' ", the source modules themselves do not change and only the newly generated object modules will be placed in the sub version directory. However, since item (1) above requires that the " blockname.CMN " file in the original directory not be changed, a redefinition of UMC$DIR will be necessary. In other words, UMC$DIR must now point to the subdirectory containing the updated versions. From this it follows that all the '*.CMN' files from the original version directory must be copied to the updated version subdirectory. Since these files are fairly small this is not a serious problem.

Users wishing to switch to a new subversion will need to redefine the logical UMC$DIR in their LOGIN.COM files.

5) A file called HIST.DOC will be maintained in the subdirectories of all new versions. This file will indicate the date and nature of changes.

V5

Welcome to the future.

UMC V5 is now available for your computing pleasure. It's features are:

-- A (nearly) complete representation of the 1994 E-787 spectrometer, including: New degrader (with lead glass) New B4 Target II (with lineprinter display) UTC (available in UMC V4) Demux RS (available in UMC V4) RSSC's (available in UMC V4) CsI endcaps (from Takeshi) Collar counters (from Takeshi) Trigger II (including Level 0 refined range using the actual masks)

-- Sample .par files to change to the 1994 configuration in $UMC_ROOT/v5.

-- Complete backward compatability with old subsystems (which are still the defaults.)

The history.txt file shows all changes from V4. There have been only a few changes that would affect users of the old spectrometer:

-- Level 1 defaults to "pass" for triggers that had no Level 1 requirement (so one doesn't need to worry about setting ISKMLV for, say, Kpi2's). -- The step size in the target is restricted for electrons, as well as heavier charged particles. I'm not sure how much effect this will have on the old target, which has a somewhat fancier cell-binning routine, but the old electr_umc made gappy electron tracks with the new target. Users of this, say, Ke4 or Dalitz analyses, may want to try the new version.

Limitations of the new spectrometer code:

-- No microcollar -- The new target is treated as one region. Small steps are taken and the energy binned into fibers in ausgab. (This is the way the old target was done.) For other degrader/target approximations, see geomtg1.cdf. Edge fibers are treated as the material outside the main square fibers, but inside a circle. -- The signal generated in the lead-glass Cerenkov is crudely rendered. -- The new refined range is calculated from time differences in the range stack without resolution smearing. On the good side, the averaging and multiplexing is done realistically. -- The number of target elements is determined without accidentals or resolution. -- The beam is simulated from the front of the degrader with simple assumptions about focus, etc. The "real beam" options will execute, but we don't have the files to run them. Pointing to the 1989-91 beam files would probably work, but doesn't seem realistic. I hope to add an option for starting with real beam rays determined from the BWPC's.