Code to generate PDG web page AtomicNuclearProperties and more
Don Groom Version 8 11 March 2014
This describes mudedxN.for, a somewhat malignant FORTRAN program which
creates all of AtomicNuclearProperties except for index.html and
several explanatory files.
As of March 2014, the version number N is 7. It calculates tables
of dE/dx for muons (including radiative contributions), writes web pages
for AtomicNuclearProperties for the 340+ materials in the data file, and
writes other output files. It has received concentrated attention
sporadically, generally to add new features. Needless to say, it doesn't
look very designed, and my successors may curse me.
It is fluent in several languages. The main code is in FORTRAN, compiled
with g77 on a linux machine. Some auxillary patch codes are in IDL. Output
are \TeX, HTML, and TEXT.
As time goes on, users will want more materials added to the data file,
atomic masses updated, and many more properties such as melting and
boiling points, refractive indices, etc. will need to be added to the data
file. The code might be improved (for instance, it doesn't calculate
stopping power for beta < 0.4, or 10 MeV for a muon). It is my hope that
this writeup, plus comments scattered through the programs, can act as an
"instruction manual" for whoever is saddled with the maintenance and
improvement of AtomicNuclearProperties in the future.
1. OVERVIEW
If you are not familiar with the files generated by this code, explore
pdg.lbl.gov/AtomicNuclearProperties. Each local link from its home page or
tables connects to a table, pdf file, or text file generated by by
mudedxN. The table gives properties of the material, and has links to
tables of stopping power generated by the code and outside links to
isotopes and gamma attenuation data (NIST).
The code also writes \TeX tables of muon dEdx(T) and a computer-readable
text file for each material. (T is the kinetic energy.)
It was modified in early 2008 to add pion interaction and collision
lengths and to make its html files less sensitive to platform. It was
changed in Feb 2009 to print effective ionization potentials in the main
tables. In 2012 the section of html_include.for for new treatment of
Z .ge. 112 elements, and to write source files for making .ps and .pdf
files from the \TeX files. At this time it was called version 7.
Data for a given material comes from PROPERTIES/propertiesN.dat
This gawdawful fixed format evolved. A real database would be far
better, but FORTRAN and I are limited. There was a massive upgrade
in going from properties7.dat to properties8.dat, along with detailed
changes almost everywhere in the code. The 2nd line of properties7.dat
and its predecessors became 2 lines in properties8.dat, implementing
better page headers and getting rid numeric html filenames; 008.html
became oxygen_gas.html, etc. See Properties8_Key.pdf.
The entries are numbered, I think consecutively, starting with 001
(hydrogen_gas). Although arbitrary, much of the code uses the index
numbers, so they are important.
Many of the files in /public_html/AtomicNuclearProperties have been
copied from /dedx. They are not necessarily the most current.
Because FORTRAN hates \TeX's backslash character, it is compiled with
g77 -fno-backslash -o mudedx8 mudedx8.for
e.g. for version 8. This not-memorable command can be copied from
the beginning of mudedx8.for.
The code is in a directory which I call 'dedx' but which can be anything.
There are 8 subdirectories, for code, input data, and output.
Subdirectory PROPERTIES contains the sacred properties8.dat and FORTRAN
code to load common block matprop with the complete content
of properties8.dat.
There are lots of subdirectories and code to do useful things, such as
create a new entry for propertiesN.date. Much of it is in IDL.
2. ORIGINS
The code was originally written to generate the tables in D.E. Groom, N.V.
Mokhov, and S.I. Striganov, "Muon stopping-power and range tables, 10
MeV-100 TeV,'' Atomic Data and Nuclear Data Tables 78, 183-356 (2001),
where nearly-identical tables for many of the materials are given. The
only part of this book which is useful is the discussion of stopping power
for muons in materials. Sergei Striganov contributed the radiative losses
part of the code. All but the tables are linked from index.html
3. MAIN PROGRAM
Call is './mudedxN materials.dat', where the materials list
materials.dat is discussed below.
mudedx6.for is presently (12/20/2012) 603 lines.
Of this, 56 lines are setup, then 'subroutine onetable' is called
for each material in the list. 'onetable' includes SACRED/texheader
A 158 line segment (not a subroutine) 'SACRED/tex_include.for' is
included to do the heavy lifting in writing the \TeX files.
A 507 line segment (not a subroutine) 'SACRED/html_include.for'
is included to write the html files and the source files for making
.ps and .pdf files out of the \TeX files generated by the FORTRAN code.
The many subrouties are discussed below
4. SUBDIRECTORIES
Needed for input data:
PROPERTIES contains the allegemeine data file propertiesN.dat,
code for reading it, and propertiesN.common, which
gives most subroutines access to all the variables
read from propertiesN.dat, plus 2 FORTRAN routines.
"fetchproN.for" puts the content of "properties8.dat"
(presently 2335 lines) into propertiesN.common, and
writes atomic_wts.dat each time the program is
executed. "adndt_stern.for" generates density effect
corrections if they are missing from the properties
entry. Note that the data file *must* provide I_eff.
(But see PROPERTIES/NEW_MATERIALS)
MUBDAT_16feb07 b values for the elements, needed to calculate
muon radiative losses for all materials.
The tables can be regenerated with Sergei's
make_mub_16feb08.for, which has had several
revisions over the years.
FORTRAN code used by mudedxN.for:
SACRED 15 key routines and Sergei's directions for calculating
nuclear interaction and collision lengths. Some of the
*.for files are code inclusions rather than subroutines.
Cross sections for inelastic and total collisions come from
subroutine SIGHA (nuclear_sergei.for).
STRINGS String manipulation tools, mostly developed by Gary
Wagman and/or Orin Dahl to manipulate strings (duh!).
PROPERIES fetchproN.for loads the common block with data from
propertiesN.dat
Output:
MUE \TeX and .dat files for muon dedx/energy. i
Plus make_muon_eloss_files, generated in html_include.for
Source it to make the .ps and .pdf , and to clean up the place.
Original \TeX files are moved to TEXSOURCE.
The .dat files are the computer-readable ascii versions (TEXT).
The first line of all the *.tex files is
\input /home/sierra/deg/texstd/mtexsis
because texsis is not installed on my machine.
Either delete these 1200 lines, or modify mudedx8.for
and run it again. So delete line 66 in tex_include.for
and line 156 (or whatever they are now) in getbval2.for,
compile, run.
MUB \TeX and .dat files for the muon b coefficients,
e.g. muB_name.tex or muB_name.dat
As above, source make_muonb_files to make the .ps and .pdf
files and clean up the place. Again note that line 1 of
\TeX files probably won't run or be useful on other machines.
It is important to note that the source files for processing files in MUE
and MUB are generated by mudedxN. In the main directory is
makepspdf_movetopublic_source which not only executes these source files
but copies all of it to AtomicNuclearProperties.
THIS (PROBABLY) MUST BE CHANGED WHEN MOVING THE CODE TO ANOTHER COMPUTER.
HTML Files of the form name.html, where name is descriptive
string such as oxygen_gas.
PROTON_ELOSS Just like muonloss_nnn.dat, except for protons:
protloss_nnn.dat. Made in Sept 2000, for most of the
elements and common materials, 118 files total.
Useful for comparing muon eloss and proton eloss.
Somewhat screwed up in format - always gives
Z, even for non-elements. Reference, not active.
Incidental output files (in main directory)
PROPERIES/atomic_wts.dat
extracted from propertiesN.dat by fetchproN.for, for
the use of getbval2.for.
substances.out
list of html commands for editing into
AtomicNuclearProperties/index.html
(for the pull-down menus).
RPP.out
mv or cp to RPP.body if it's safe. Longer explanation
below.
InterLength.out
Dump of Z, A, density, dEmin, X0, lam_I, lam_pi_I,
E_c(electron), E_c(positron), and state for the
chemical elements, for use in making plots etc. Some repeat
entries because of different physical states for some elements.
5. USAGE
If you are generating tables for less than everything, you probably want to
empty what's there:
\rm HTML/*.html
\rm MUB/muB_*
\rm MUE/muE_*
Call to generate everything for a list of materials is
./mudedx8 mat_table_name.list
where 'mat_table_name.list' is the input file telling it which substances
to do. It starts (i4) with ind, the index of the material. The rest
of the identifier might be useful to the user but unused by the program
e.g.
> more short.dat
110 Anthracene
78 Platinum
301
26 Iron,probably
>
Probably will want to use
elements.list
inorganics.list
organics.list
and short lists temp.list to generate the appropriate kinds of output.
mat_table.dat to generate everything
RPP.dat
See RPP* in the output section below.
There are usually also short special-purpose *.dat files lying around,
as well as some .pro (IDL) files.
There are other special files. Look before you delete.
ESPECIALLY, be careful with InterLength*
Source table of properties is the sacred 'PROPERTIES/propertiesN.dat'
The obscure format is explained in 'PROPERTIES/propertiesN.common',
and the syntax in PROPERTIES/Properties6_Key.pdf
(Sorry; it grew, and besides I was stuck with fixed-format FORTRAN.)
Chemical formula notation is explained in note [1] at end.
Directions for adding a new material are given in note [3] at end.
(There is no note [2] I think.)
OUTPUTS:
On execution of './mudedx7 something.dat' tables get loaded into these
directories with the output for whatever index numbers is in 'something.dat'
RPP.out
\TeX source file to make Table 6 in RPP. To do this,
(a) Run the code with the .dat file with just the stuff you want
in Table 6; at the moment this is called RPP.dat
(b) \cp RPP.out RPP.body
(c) Run RPP.tex
(d) After editing: combine solid/liquid lines to have RPP format.
(This affects only density and sometimes refractive index.)
Remove and/or edit most chemical formulae so that the table
fits on one page in portrait format.
6. SUBROUTINES, FUNCTIONS, AND CODE SEGMENTS INCLUDED BY MUDEDX8.FOR
'PROPERTIES/fetchpro8.for'
'PROPERTIES/adndt_stern.for'
'SACRED/btot.for' ! interpolates to find btot etc for given energy
'SACRED/dedx2.for' ! basic electronic dedx routine
'SACRED/dedxmin2.for' ! iterates to find minimum, using dedx2
'SACRED/etex.for' ! writes E format as TeX string
'SACRED/mucrit.for' ! iterates to find muon crit energy
'SACRED/linestr.for' ! assembles ascii string of real numbers in TeX
'SACRED/getbval2.for' ! form weight-fraction weighted b values
'SACRED/X0_recip.for'
'SACRED/nuclear_sergei.for'
'SACRED/alfnum.for'
'SACRED/dedx_ep.for'
C PDG string manipulation routines from Orin 27jun06
C gconstn.for gimplic.for sindex.f slength.f slower.f ssubsti.f supper.f
'STRINGS/ssubsti.f'
'STRINGS/slength.f'
'STRINGS/sindex.f'
'STRINGS/sfirst_don.f'
'STRINGS/slower.f'
PDG string manipulation routines in main directory:
gconstn.for
gimplic.for
sindex.f
slength.f
ssubsti.f
Some of the subroutines also input code strings.
Also needs PROPERTIES/properties8.common:
PROPERTIES/properties8.dat This is the most sacred data file from which
*all* information about the materials is found. Make frequent backups
if editing it. The obscure and mysterious format is explained in
properties3.common (sorry, it grew)
7. OTHER ROUTINES:
make_mat_table.for
To make file mat_table.out listing all the materials in properties8.dat
in the format that mudedx8 wants. Pieces of this can be edited into the
'mat_table_name' file for mudedx8. E.g. elements01-20.dat. Only
advantage over a list of numbers from 1 to NMAT (1 in i4 format) is
the explanatory text, which is ignored but makes it easier to rea.
alfz.for Short test program to understand how to make format entry such
as //fmtsig//
plot_nuclear.for Sergei's program to test the generation of nuclear
interaction and collision lengths
plot_nuclear.pro IDL program to make plot of nuclear interaction and
collision lengths for explain.html in AtomicNuclearProperties
gconstn.for is a relic of some kind; looks like Sergei's but is not
refered to anywhere
sort_typemat.pro IDL routine to take substances.for and sort it into
files for E(lement), I(norganic), etc. for use in making the pulldown
menus for the main AtomicNuclearProperties/index.html. Some reordering
is needed, and a few silly substances should be dropped.
9. ADDING A NEW MATERIAL (at end of properties3.dat)
First make a backup of propertiesN.dat, of course.
You MUST come up with a reasonable excitation potential.
Best treatment is in
Atomic Data and Nuclear Data Tables 78, 183-356 (2001), ICRU37
(Photocopy of this elusive mss. is in Groom's office, or was.)
Also see
D.E. Groom, N.V. Mokhov, and S.I. Striganov, ``Muon
stopping-power and range tables, 10 MeV--100 TeV,''
Atomic Data and Nuclear Data Tables 78, 183-356 (2001).
The relevant parts are in AtomicNuclearProperties/adndt.pdf
(37 pages), linked to the main AtomicNuclearData page.
Now we need the Sternheimer coefficients.
fetchpro6.for checks to see if the next entry
on the 3rd line (cbar, the first Sternheimer coefficient) is
zero; if so, it generates the them, using subroutine adndt_stern.for
Not as accurate as more expert calculations/measurements of I.
HOWEVER, IDL routines exist in PROPERTIES/NEW_MATERIALS to make
all this "easy." See note [3] below.
10. FINAL PROCESSING
.ps and .pdf files need generated from the .tex files. After this,
the *.dvi and *.log files need deleted, and *.tex moved to TEXSOURCE.
This is done by sourcing the first few lines of makepspdf_movetopublic_source
When working on my computer, I keep the "working" copy of
AtomicNuclearProperties in
/home/sierra/deg/public_html/AtomicNuclearProperties/
You should change this to whatever you like.
See the rest of source file 'makepspdf_movetopublic_source'
In this case I wanted to start out with
\rm so that only the new pages are added. That way I can pass
just the new/revised material to Piotr.
NOTES:
[1] Notation for subscripts in chemical formulae is like C#4%H#10%,
where '#' means 'begin subscript' and '%' means 'end subscript.'
When writing TeX file, the code
replaces "#" by '\sub{'
replaces '%' by '}'
and when writing HTML file the code
replaces "#" by '<SUB>'
replaces '%' by '</SUB>
[2] Lost in history.
[3] Adding new material.
> cd PROPERTIES/NEW_MATERIALS
Read AAREADME, skipping steps 1-3 unless atomic numbers or I_eff's have
changed.
Look at/run make_entry.pro. It uses Bragg addition to estimate Ieff. The
input file, e.g. LaBr3.dat, looks like
LaBr3 Lanthanam bromide [LaBr%3#]
5.29
La 1
Br 3
2nd line is the density. Rest is obvious from the propertiesN.dat
entry:
---------------------------------------------------------------------------
ind LaBr3 5 -1.0000000000 0.42787 5.2900e+00 5.2900e+00 S 2 1 1 I
lanthanum_bromide
lanthanum bromide (LaBr%3#)
454.5 0.0000 0.0000 0.0000 0.00000 0.0000 0.00
57 1.000000 0.366875
35 3.000000 0.633124
Note: Ieff calculated using the ICRU37 algorithm given in Table 5.1
----------------------------------------------------------------------------
Add the (unique) index number (ind) by hand; append to propertiesN.dat