.. _input-file-gen: Input File Generation ===================== .. _automatic-input-file-gen: Automatic Input File Generation ------------------------------- It is frequently desired to create a MG or CE library based on a selected set of ENDF/B formatted files. The auxiliary AMPX code ExSite greatly helps with the task of preparing the input files. This section focuses on the background of input file generation, whereas the use of ExSite is described in :numref:`using-exsite`. ExSite first parses the desired ENDF/B formatted file and generates an abbreviated list of information pertinent to library creation. The list is stored in XML format to allow easy human and machine readability. The list is used in conjunction with templates that contain the input descriptions for the AMPX modules necessary to generate the desired library. In general, more than one template is needed to generate the final library. The next section describes the creation of the abbreviated ENDF list in more detail. The format of the templates is described later. .. _ENDF-listing: ENDF Listing ~~~~~~~~~~~~ The templates used to generate AMPX input files require a list of ENDF information which is assumed to be in xml format and must contain a root element named ``Materials``. The information is automatically extracted from ENDF/B formatted files. The given file can contain one or more evaluations. For each evaluation, an XML element named ``Material`` is added to the XML file. The element contains attribute/value pairs for every piece of information extracted from the ENDF evaluation. The available attributes are listed in :numref:`tab-15`. Since an extensible XML format is used, more attribute value pairs may be added in the future. .. tabularcolumns:: |m{3cm}|m{11cm}| .. table:: Field names automatically extracted from the ENDF evaluation. :name: tab-15 :align: center :class: longtable +----------------+----------------------------------------------------------------------+ | Name | Description | +================+======================================================================+ | tape | The full name of the file containing the evaluation | +----------------+----------------------------------------------------------------------+ | filename | The name (without the path) of the file containing the evaluation | +----------------+----------------------------------------------------------------------+ | endf | The endf material number | +----------------+----------------------------------------------------------------------+ | za | | The standard material charge number | | | | Retrieved from C1 position in first record of File 1 | +----------------+----------------------------------------------------------------------+ | awr | | The mass ratio of the material | | | | Retrieved from C2 position in first record of File 1 | +----------------+----------------------------------------------------------------------+ | dbrcnuclide | Set to "yes" if a >= 200. | +----------------+----------------------------------------------------------------------+ | tag | | | | | A name that uniquely describes the material | | | | Constructed from columns 1--11 of the fifth record of File 1 | | | | (Denoted ZYNAM in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | | mod | | The ENDF evaluation modification number. | | | | Retrieved from N2 position in first record of File 1 | | | | (Denoted NMOD in ENDF manual) | +----------------+----------------------------------------------------------------------+ | rel | | The ENDF evaluation release number. | | | | Retrieved from L1 position in third record of File 1 | | | | (Denoted LREL in ENDF manual) | +----------------+----------------------------------------------------------------------+ | nlib | The library source (ENDF, JEFF, etc.) | +----------------+----------------------------------------------------------------------+ | eval | | The date of the ENDF evaluation | | | | Retrieved from columns 23--32 of the fifth record of File 1 | | | | (Denoted EDATE in ENDF manual) | +----------------+----------------------------------------------------------------------+ | awi | Mass ratio of the incident particle | +----------------+----------------------------------------------------------------------+ | zai | ZA value of the incident particle | +----------------+----------------------------------------------------------------------+ | | | Set to "yes" if incident particle is a neutron. Otherwise set to | | neutron | "no" | | | | Based on C1 value in third record of File 1 | | | | (Denoted AWI in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | Set to "yes" if incident particle is a gamma. Otherwise set to | | gamma | "no" | | | | Based on C1 value in third record of File 1 | | | | (Denoted AWI in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | The name of the authors of the ENDF evaluation | | author | | Retrieved from columns 34--66 of the fifth record of File 1 | | | | (Denoted AUTH in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | The name of the originating laboratory | | lab | | Retrieved from columns 12--22 of the fifth record of File 1 | | | | (Denoted ALAB in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | The original distribution date of the ENDF evaluation | | dist | | Retrieved from columns 23--32 of the sixth record of File 1 | | | | (Denoted DDATE in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | Date of the last revision of the ENDF evaluation | | rdate | | Retrieved from columns 34--43 of the sixth record of File 1 | | | | (Denoted DDATE in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | The version number of the library | | rev | | Retrieved from the N2 value of the third record of File 1 | | | | (Denoted NVER in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | Set to "true" if the material is metastable, otherwise set to | | metaStable | "false" | | | | Determined from columns 1--11 of the fifth record of File 1 | | | | (Denoted ZYNAM in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | Library format | | version | | Retrieved from N2 position in second record of File 1 | | | | (Denoted NFOR in ENDF manual) | +----------------+----------------------------------------------------------------------+ | | | State number of the target nucleus. | | lis | | Retrieved from L2 position in second record of File 1 | +----------------+----------------------------------------------------------------------+ | | Set to "yes" if File 1 contains any of the following reaction: | | fission | 452, 455, 456, 458 | +----------------+----------------------------------------------------------------------+ | | Set to "yes" if the evaluation contains a File 2 | | file2 | | +----------------+----------------------------------------------------------------------+ | | Contains the number of isotopes given in File 2 | | nis | | +----------------+----------------------------------------------------------------------+ | resonance | If File 2 is present and contains resonance parameters for the | | | resolved resonance range, | | | then it is set to: | | | | | | - "SLBW" if the resonance parameters are given | | | in Single Level Breit--Wigner format. (ENDF parameters LRF=1) | | | | | | - "MLBW" if the resonance parameters are given in Multi | | | Level Breit--Wigner format. (ENDF parameters LRF=2) | | | | | | - "RM" if the resonance parameters are | | | given in Reich--Moore format. (ENDF parameters LRF=3) | | | | | | - "AA" if the resonance parameters are given in Adler--Adler format. | | | (ENDF parameters LRF=4) | | | | | | - "RML" if the resonance parameters are given in R-Matrix Limited | | | format. (ENDF parameters LRF=7) | | | | | | If more than one resolved resonance region is given for the | | | evaluation, the value reflects the format for the last resonance | | | region given. | +----------------+----------------------------------------------------------------------+ | res | If File 2 is present and contains resonance parameters for one or | | | more resolved resonance regions the value is set to "yes" | +----------------+----------------------------------------------------------------------+ | unres | If File 2 is present and contains resonance parameters for | | | one or more unresolved resonance regions the value is set to "yes" | +----------------+----------------------------------------------------------------------+ | scattering | If File 2 is present set to the potential scattering cross section. | | | It is determined from the first resolved resonance range for each | | | isotope given in the evaluation as follows (if the file only contains| | | an unresolved resonance range, the radius given in that section | | | is used): | | | | | | 1. Set the scattering radius ap to AP (see ENDF manual) if NRO = 0. | | | If NRO > 0, set ap to the first radius given in the table of | | | energy radius pair. If LRF=3 and ap=0.0, select first APL (see | | | ENDF manual) | | | 2. If only an unresolved region is present, select AP from it | | | 3. If LRF=7 select APE from the first group of | | | :math:`\mathrm{J}^{\pi}` values and the second channel | | | 4. Calculate the potential scattering cross section as | | | :math:`12.56637061 \times a p^2` | | | 5. If more than one isotope is present, add the cross section | | | data calculated in step 2 according to the abundance of each | | | isotope | +----------------+----------------------------------------------------------------------+ | file3 | Set to "yes" if the evaluation contains a File 3 | +----------------+----------------------------------------------------------------------+ | | | | file4 | Set to "yes" if the evaluation contains a File 4 | +----------------+----------------------------------------------------------------------+ | | | | file5 | Set to "yes" if the evaluation contains a File 5 | +----------------+----------------------------------------------------------------------+ | | | | totalFission | Set to "yes" if the evaluation contains a File 5 | | | and File 5 contains a section for MT=18 (total fission) | +----------------+----------------------------------------------------------------------+ | | | | partialFission | Set to "yes" if the evaluation contains a File 5 | | | and File 5 contains a section for MT=19, MT=20, MT=21 or MT=38 | | | (second chance fission) | +----------------+----------------------------------------------------------------------+ | | | | file6 | Set to "yes" if the evaluation contains a File 6 | +----------------+----------------------------------------------------------------------+ | | | | AWP0 | Set to "yes" if File 6 contains photon production yield matrices. | | | This is true if any of the sections has a mass | | | ratio of 0 for the product. In addition if LAW=2, the mass ratio | | | can contain | | | the gamma energy if the charge for the outgoing particle is 0 | +----------------+----------------------------------------------------------------------+ | | | | file7 | Set to "yes" if the evaluation contains a File 7 | +----------------+----------------------------------------------------------------------+ | | | | file7temps | If File 7 exists, it contains the list of | | | temperatures at which the moderator data were evaluated | +----------------+----------------------------------------------------------------------+ | | | | file12 | Set to "yes" if the evaluation contains a File 12 | +----------------+----------------------------------------------------------------------+ | | | | file13 | Set to "yes" if the evaluation contains a File 13 | +----------------+----------------------------------------------------------------------+ | | | | file23 | Set to "yes" if the evaluation contains a File 23 | +----------------+----------------------------------------------------------------------+ | | | | covariance | Set to "yes" if the evaluation contains File 31, File 32 or File 33 | +----------------+----------------------------------------------------------------------+ | | | | chicov | Set to "yes" if the evaluation contains File 35 | +----------------+----------------------------------------------------------------------+ The XML list containing the parameters automatically extracted from the ENDF evaluation is not sufficient to generate the input files. An additional XML file is used containing information concerning metastable nuclei and thermal moderator data. This configuration file contains a root element ``ConfigFile`` and three sections. If parsing one or more ENDF formatted files, a configuration file is automatically created with some default values. .. note:: The values should be reviewed before actually using the configuration file. In the final library, the nuclei are normally identified by their ZA value and not by the ENDF material number. This makes it necessary to use a different ID in some cases in order to avoid duplication. - ``endf`` contains the ENDF MAT number of the evaluation for which the final library ID should be changed. - ``realza`` contains the actual ZA value of the nucleus - ``scaleza`` contains the ID to be used in the final library - ``name`` label used in the SCALE standard composition library By default, the section contains new ID value for H1 (changed to 8001001) and H2 (changed to 8001002). .. _meta-stable: Meta Stable Nuclei ^^^^^^^^^^^^^^^^^^ Since the ZA value for meta-stable nuclei is the same as for the stable form, the ID in the final library needs to be changed in order to avoid duplicate entries with the same ID value. The section is contained in an element named metastable, which contains one or more nuclei elements. The nuclei element has three attributes: - ``endf`` contains the ENDF MAT number of the evaluation for which the final library ID should be changed - ``realza`` contains the actual ZA value of the nucleus - ``scaleza`` contains the ID to be used in the final library By default, an entry is created for each meta-stable nuclei contained on the ENDF tape being parsed. The new ID is set to LISO\*1000000+ZA. .. _thermal-moderators: Thermal Moderators ^^^^^^^^^^^^^^^^^^ In the creation of the final library, thermal moderators must be treated separately, as they only contain data in the thermal range. The data must be combined with one or more evaluation in the fast range. In addition the final ID should depend on the thermal data, as well as the fast data connected to it. The section is contained in an element named ``thermal``, which contains one or more ``nuclei`` elements. Each ``nuclei`` element has two attributes: - ``endf`` contains the ENDF MAT number of the evaluation for which the final library ID should be changed - ``realza`` contains the actual ZA value of the nucleus In addition, each ``nuclei`` element has one or more ``fastMat`` elements listing the evaluations to be used in the fast region. Each ``fastMat`` element contains the following attributes: - ``endf`` contains the ENDF MAT number evaluation to be used in the fast region - ``scaleza`` contains the ID to be used in the final library for the combined thermal and fast data - ``name`` specifies the name used in the SCALE standard composition library An evaluation is recognized as a thermal moderator if File 7 is present. In this case, an entry is automatically added. :numref:`tab-16` lists the values that are automatically selected. Please note that these are the material numbers as given in the ENDF manual. Some of the actual material numbers used in ENDF/VI and ENDF/VII differ from this designation. Please review the automatically generated configuration file for consistency. Comments containing the tag for each thermal and fast evaluation are included in the configuration file and should help in this task. .. table:: Thermal material numbers recognized (See ENDF manual for detail). :align: center :name: tab-16 +---------------+--------------------+--------------------+-------------+ | | | | | | MAT number | Description | Fast evaluation | SCALE ID | +===============+====================+====================+=============+ | | | | | | 1 | Water | Bound with H1 | 1001 | +---------------+--------------------+--------------------+-------------+ | | | | | | 2 | Para Hydrogen | Bound with H1 | 5001001 | +---------------+--------------------+--------------------+-------------+ | | | | | | 3 | Ortho Hydrogen | Bound with H1 | 4001001 | +---------------+--------------------+--------------------+-------------+ | | | | | | 7 | H in ZrH | Bound with H1 | 7001001 | +---------------+--------------------+--------------------+-------------+ | | | | | | 11 | Heavy Water | Bound with H2 | 1002 | +---------------+--------------------+--------------------+-------------+ | | | | | | 11 | Para Deteurium | Bound with H2 | 5001002 | +---------------+--------------------+--------------------+-------------+ | | | | | | 13 | Ortho Deuterium | Bound with H2 | 4001002 | +---------------+--------------------+--------------------+-------------+ | | | | | | 26 | Be | Bound with Be9 | 3004009 | +---------------+--------------------+--------------------+-------------+ | | | | | | 27 | BeO | Bound with Be9 | 5004009 | | | +--------------------+-------------+ | | | | | | | | Bound with O16 | 5008016 | +---------------+--------------------+--------------------+-------------+ | | | | | | 28 | Be\ :sub:`2`\ C | Bound with Be9 | 7004009 | | | +--------------------+-------------+ | | | | | | | | Bound with C | 7006000 | +---------------+--------------------+--------------------+-------------+ | | | | | | 29 | Be in BeO | Bound with Be9 | 5004009 | +---------------+--------------------+--------------------+-------------+ | | | | | | 31 | Graphite | Bound with C | 3006000 | +---------------+--------------------+--------------------+-------------+ | | | | | | 33 | l-Methane | Bound with H1 | 7001001 | +---------------+--------------------+--------------------+-------------+ | | | | | | 34 | s-Methane | Bound with H1 | 2001001 | +---------------+--------------------+--------------------+-------------+ | | | | | | 37 | Polyethylene | Bound with H1 | 9001001 | +---------------+--------------------+--------------------+-------------+ | | | | | | 40 | Benzene | Bound with h1 | 6001001 | | | +--------------------+-------------+ | | | | | | | | Bound with C | 5006000 | +---------------+--------------------+--------------------+-------------+ | | | | | | 46 | O in BeO | Bound with O16 | 5008016 | +---------------+--------------------+--------------------+-------------+ | | | | | | 58 | Zr in ZrH | Bound with Zr | 1040000 | | | +--------------------+-------------+ | | | | | | | | Bound with Zr90 | 1040090 | | | +--------------------+-------------+ | | | | | | | | Bound with Zr91 | 1040091 | | | +--------------------+-------------+ | | | | | | | ... | +---------------+--------------------+--------------------+-------------+ | | | | | | 75 | UO\ :sub:`2` | Bound with O16 | 7008016 | | | +--------------------+-------------+ | | | | | | | | Bound with U232 | 1092232 | | | +--------------------+-------------+ | | | | | | | | Bound with U233 | 1092233 | | | +--------------------+-------------+ | | | | | | | | ... | | +---------------+--------------------+--------------------+-------------+ | | | | | | 76 | UC | Bound with C | 8006001 | +---------------+--------------------+--------------------+-------------+ | | | | | | | | Bound with U232 | 1092232 | +---------------+--------------------+--------------------+-------------+ | | | | | | | | Bound with U233 | 1092233 | +---------------+--------------------+--------------------+-------------+ If the ENDF material number for a thermal moderator is not found in :numref:`tab-16`, it is bound with an evaluation with the same Z and A value. This may not lead to the desired result if the ZA value is not set to a realistic value in ENDF. .. _templates: Templates ~~~~~~~~~ To generate input files, the XML lists described previously are combined with templates in XML format. The templates are usually part of a user template used in ExSite to automatically generate input files. This section describes the use of the template only. The template is an XML file containing elements instructing the parser on how to interpret the input. The main branching elements are: - ``openFile`` with attribute name, opens a file for writing. The name attribute contains the name of the file. Output will only be written to files that have previously been opened. This element can appear anywhere in the template. The element can contain an attribute newInput with values yes or no. If the value is no, the output file is opened in append mode, otherwise a new file is created. - ``closeFile`` with attribute name, closes a previously opened file. The name attribute contains the name of the file. This element can appear anywhere in the template. - ``writeFile`` with attribute name, opens a file for writing. The name attribute contains the name of the file. The only children allowed are XML CDATA sections and text elements (see below for more information). Any information contained in one of these child elements will be written into the output file. This element can appear anywhere in the template. Please note that any ``writeFile`` element needs to be closed before starting or closing any other element but a ``text`` element or a CDATA section. - ``text`` contains text to be written to the output file. It may contain an attribute ``restrict``. Please see below for more information. This element can only appear inside a ``writeFile`` element. - ``loop`` start a loop over all evaluations. It may contain an attribute ``restrict``. Please see below for more information. Looping elements may be nested. The element can appear anywhere in the templates except inside a ``writeFile`` element. - ``last`` is an element that can appears anywhere in a ``loop`` element. It is assumed that the element contains one or more ``writeFile`` elements which will be written to the file only if this is the last evaluation to be processed in the parent ``loop`` element. - ``first`` is an element similar to the last element except that its content is only used if the first evaluation of the parent ``loop`` element is processed. - ``notLast`` is an element that can appear anywhere in a ``loop`` element. It is assumed that the element contains one or more ``writeFile`` elements which will be written to the file for anything but the last evaluation to be processed in the parent ``loop`` element. - ``notFirst`` is an element similar to the ``notLast`` element, except it is processed for anything but the first evaluation to be processed in the parent ``loop`` element. - ``arrayLoop`` with attribute ``value`` is a special loop that loops over all values listed in the ``value`` attribute. Values are assumed to be separated by space. This loop type cannot be nested and cannot contain any ``last``, ``first``, ``notLast`` or ``notFirst`` elements. - ``thermalLoop`` loops over all fast evaluations that may be bound with the current thermal moderator. If the evaluation is not a thermal moderator, this loop will be ignored. This loop type cannot be nested and cannot contain any ``last``, ``first``, ``notLast`` or ``notFirst`` elements. - ``exclude`` with attribute ``run``. If the value of run is ``no``, this section of the template is ignored. Inside a text element or in any attribute value, the function *writeData()* will be substituted by values retrieved from the XML file listing the abbreviated ENDF information. The function *writeData* may have several arguments separated by commas. The first argument is always a reference to the field to be written, and the last two arguments are always optional and contain the length of the field and the fill character. If the first argument is any of the attribute names listed in :numref:`tab-15`, the value of that argument will be substituted. For example if processing :sup:`232`\ U, then *writeData(endf)* will be substituted by 9219 and *writeData(endf,6,\*)* will be substituted by \*\*9219. In addition to the values listed in :numref:`tab-15`, the values listed in :numref:`tab-17` can also be used. .. raw:: latex \clearpage .. tabularcolumns:: |m{4cm}|m{12cm}| .. table:: Additional substitution values that can be used in templates. :align: center :name: tab-17 :class: longtable :widths: 15 85 +-------------------+--------------------------------------------------------------------------------------------+ | | | | z | The atomic number of the current evaluation | +-------------------+--------------------------------------------------------------------------------------------+ | | | | a | The mass number of the current evaluation | +-------------------+--------------------------------------------------------------------------------------------+ | | | | chem | The chemical name of the current evaluation | +-------------------+--------------------------------------------------------------------------------------------+ | | | | source | The source of the library (endf, jeff, etc.). | | | This is just an alias for nlib. | +-------------------+--------------------------------------------------------------------------------------------+ | | | | library | A string representation of source which is used in some filenames | +-------------------+--------------------------------------------------------------------------------------------+ | | | | scaleid | | A special ID value used in the library, calculated as: | | | | **endf + 10000 \* rel + 1000000 \* rev** | | | | (See :numref:`tab-15` for definition of **endf**, **rel** and **rev**.) | +-------------------+--------------------------------------------------------------------------------------------+ | | | | changedza | The ZA value of the ID or the ID designated in the configuration file | +-------------------+--------------------------------------------------------------------------------------------+ | | | | thermalscaleid | The same as scaleid except calculated with the endf, rel | | | and rev number for the thermal moderator. (If requesting scaleid for a thermal moderator, | | | the output will be the scaleid for the first fast evaluation bound to the moderator.) | +-------------------+--------------------------------------------------------------------------------------------+ | | | | thermalEvals | The number of evaluations to be used in the fast region if the | | | current evaluation is a thermal moderator (In all other cases it is 0.) | +-------------------+--------------------------------------------------------------------------------------------+ | | | | date | The current date (The function can contain a second argument | | | giving the desired format for the date.) | +-------------------+--------------------------------------------------------------------------------------------+ | | | | loopindex | This substitution value that can only appear inside a loop element. | | | (It is the index of the element in the XML listing currently being processed. | | | The element can have an additional argument giving the offset. For example, | | | if the current index is 2 and the offset is 60, the value 62 is printed.) | +-------------------+--------------------------------------------------------------------------------------------+ | | | | loopnumber | A substitution value that can only appear inside a loop element, equal | | | to the number of times the content of the loop will be executed. | | | (The element can have an additional argument giving the offset.) | +-------------------+--------------------------------------------------------------------------------------------+ | | | | loopcount | A substitution value that can only appear inside a loop element; | | | the number of times the loop is being processed, including the current execution. | | | (This is different from loopindex if the loop has a restrict attribute. | | | The element can have an additional argument giving the offset.) | +-------------------+--------------------------------------------------------------------------------------------+ | | | | array_value | A substitution value that can only appear inside an arrayLoop element; | | | substituted by the current value of the loop variable | +-------------------+--------------------------------------------------------------------------------------------+ | | | | array_number | A substitution value that can only appear inside an arrayLoop element; | | | substituted by the current index of the array loop. | | | (The function can have an additional argument given the offset to be added | | | to the index. For example, if the current index is 2 and | | | the offset is 60, the value 62 is printed.) | +-------------------+--------------------------------------------------------------------------------------------+ | | | | array_length | A substitution value for the number of items in the value of | | | the element listed as the second argument. | +-------------------+--------------------------------------------------------------------------------------------+ In the case of a thermal moderator, the values for the fast evaluations to be bound with the moderator are often needed in the input file. Therefore, each of the function arguments listed in :numref:`tab-15` and :numref:`tab-17` can have a postfix of "fast1," "fast2" . . . . If this postfix is found, the corresponding value is retrieved not from the current evaluation but from the first, second . . . fast evaluation to be bound with this thermal moderator. If the current evaluation is not a thermal moderator, the postfix is ignored, and the value for the current evaluation is substituted. The field changedza can have postfix values of thermal1, thermal2 . . . in order to retrieve the value to use for the ID in the final library (changedzafast1, changedzafast2. . . would retrieve the ZA value of the evaluation used in the fast region). As the number of fast evaluations to be bound with a thermal moderator is not known while writing the template, the loop element ``thermalLoop`` is provided. In this loop, each argument can have a further postfix "_thermNum" which will be substituted by 1,2 . . . until all fast evaluations have been processed. For example, to list the endf mat number and the new scale ID for all fast evaluations of a given thermal moderator, the following snippet is used: :: For thermal moderator writeData(tag) with mat=writeData(endf) use Fast: writeData(tagfast_thermalNum) with endf mat=writeData(endffast_thermalNum) and new id of writeData(changedzafast_thermalNum) If preparing a coupled library, it is necessary to find a gamma evaluation associated with the current neutron evaluation. If the XML list contains neutron evaluations and gamma evaluations, the template parser will attempt to pair the two together based on the Z value. An evaluation is recognized as a gamma evaluation if the incident particle is a gamma and the evaluation contains File 23 data. An evaluation is recognized as a neutron evaluation if the incident particle is a neutron and the evaluation contains File 3 data. If an associated gamma evaluation is found, all the tags listed in :numref:`tab-15` and :numref:`tab-17` can have a postfix "gamma." If the postfix is found, the corresponding value is retrieved not from the current evaluation, but from the associated gamma evaluation. If the current evaluation is a thermal moderator, then the gamma evaluation is associated with the evaluations to be used in the fast region. In this case, a postfix of "gammathermal1," "gammathermal2" . . . must be used. The ``loop`` and the ``text`` element take an optional attribute ``restrict`` that selects only certain evaluations. The ``restrict`` attribute value is a comma-separated list of restrictions to be applied. If a restriction is prefixed with a "-" then the ``loop`` or ``text`` will only be executed for evaluations that do not fulfill the requested property. If a restriction is prefixed with a "+" then the loop or text will only be executed for evaluation that do fulfill the requested property. The "+" prefix is only needed if one or more restrictions are given in a restrict argument; otherwise, "+" is assumed. If more than one restriction is given and all restrictions are prefixed with a "+" then the body will only be executed for evaluations that fulfill **ALL** of the restrictions: i.e., a logical and is assumed; otherwise a logical or is assumed. A restriction can be constructed from all of the tags given in :numref:`tab-15` and :numref:`tab-17`. The postfix operators for thermal moderators and associated gamma evaluations are also allowed. The restriction is created by giving the desired tag followed by the desired value. For example "+file3(yes) +neutron(yes)" selects all neutron evaluations excluding thermal moderators. In addition, the following shortcut restrictions are also allowed: - ``gamma`` restricts to neutron evaluations that have an associated gamma evaluation - ``thermal`` restricts to thermal moderator evaluations - ``metastable`` restricts to meta stable nuclei - special restricts to nuclei for which the library ID is changed (These are the nuclei listed in the ``specialNuclei`` section of the configuration file.) - ``fastforthermal`` restricts to nuclei that are used as a fast evaluation for any of the thermal moderators in the listing Examples describing custom templates for ExSite are provided later in this section. .. _exsite-files: ExSite Files ------------ ExSite is used to generate the XML listings described above and to process the templates. It also serves as a GUI to read and create AMPX input files. The user input for the various AMPX modules and the templates is described in XML formatted files. The XML files for the module input are created from input descriptions in the module source files. The user template input is usually much simpler than for the module input and is created by hand. This section describes the xml formats used by ExSite, concluding with some examples of custom template files. Instructions on how to run ExSite are given in :numref:`using-exsite`. Module descriptions are given in an XML file with elements for each input parameter. The input parameters are subdivided into groups, where the parent group is the module itself. The input parameters are described in an element giving the name of the parameter. All input parameters can have the attributes listed in :numref:`tab-18`. Additional attributes may be available depending on the type. Each input element also can contain the elements listed in :numref:`tab-19`. Additional elements may be needed depending on the type of the input parameter. .. tabularcolumns:: |\Y{.25}|\Y{.15}|\Y{.20}|\Y{.40}| .. table:: Attributes available for input parameters :name: tab-18 :align: center :class: longtable +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | Name | Required | Possible choices | Description | +====================+=============+=====================+=========================================================================================+ | | | | | | type | yes | listed below | The type of the variable | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | required | no | yes | Indicates whether this language element is required | | | | | | | | | no | *Default is no*. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | keyword | no | yes | Indicates whether a keyword is required to start the parameter, | | | | | as in **keyword=value** | | | | no | | | | | | *Default is no*. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | nameUsed | no | | Value to use instead of the name if the parameters are **keyword=value** | | | | | (Required when spaces are needed in the keyword; the attribute can contain | | | | | one or more values in a space-separated list, and in this case, all values | | | | | in that list are recognized as valid keywords.) | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | attachMeaning\_\* | no | | If **nameUsed** supplies a space-separated list of keywords, attaches | | | | | different descriptions to each of these keywords (If desired, | | | | | a corresponding attribute **attachMeaning_keyword** must appear for each keyword listed | | | | | in **nameUsed**) | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | keywordSeparator | no | | The separator between **keyword=value** | | | | | | | | | | *Default is =* | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | caseSensitive | no | yes | The comparison for keywords to be entered as case sensitive. | | | | | | | | | no | *Default is no*. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | before | no | Name of input | If this input object is used, it must appear before the indicated input object. | | | | | The indicated input object must be a required one. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | after | no | Name of input | If this input object is used, it must appear after the indicated input object. | | | | | The indicated input object must be a required one | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | appendEol | no | yes | Used when the input must end in an end of line | | | | | | | | | no | *Default is no*. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | hide | no | yes | Used when the indicated input must be hidden from the user | | | | | | | | | no | *Default is no*. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | deprecated | no | yes | Used when the parameters are deprecated (used in the text but not in the GUI) | | | | | | | | | no | *Default is no*. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | depends | no | | Name of the input value this input depends on (The value can | | | | | contain +, -, \*, and /. In this case it is assumed that the input parameters | | | | | contain numbers combined to calculate the final value. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | compValue | no | | Value used to compare with resulting value if **depends** is set | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | compare | no | eq | | Used to compare the value of the dependent input object to **compValue**: | | | | | | | | | ne | | eq: compares **for equality** | | | | | | | | | gt | | ne: compares **that not equal** | | | | | | | | | lt | | gt: converts **compValue** and **value** of the dependent input object to a float and | | | | | | compares **as greater than** | | | | | | | | | | | lt: converts **compValue** and **value** of the dependent input object | | | | | | to a float and compares **as less than** | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | postfix | no | | A postfix to be added after the value | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | repeat | no | exsite_unlimited | If **exsite_unlimited**, the block can be repeated any number of times (If | | | | | a number, gives the number of times this block repeats. Otherwise it | | | | | is the name of a valid input object. The value of this input object is | | | | | converted to a number which gives the number of times this block repeats. | | | | | The value can contain +, -, \*, and \/. In this case, it is assumed that the | | | | | input parameters contain numbers combined to calculate the final value.) | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | repeatIsUpper | no | yes | Indicates that the value given in **repeat** is an upper limit only | | | | | | | | | no | | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | repeatAtLeastOnce | no | yes | Indicates that the value given in **repeat** is an upper limit only, but | | | | | the value must be given at least once | | | | no | | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | lineLength | no | | The allowed length of line. If -1, no line length limit is assumed. | | | | | Inherited from parent if not set. | | | | | | | | | | *Default is -1*. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | allowComments | no | yes | Allows comments in the coding (Inherited from parent if not set.) | | | | | | | | | no | *Default is yes*. | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | groupTag | no | | A name that groups a number of input elements into a logical group; | | | | | used to display the input parameters together in the GUI | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | listPanel | no | yes | Determines how the input parameter is displayed in the GUI if it is | | | | | a group of input parameters | | | | no | | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ | | | | | | automaticEnable | no | yes | If this input parameter depends on the value of another parameter, | | | | | it will be unchecked in the GUI. If this attribute is set to "yes," | | | | no | then the input parameter will be selected in the GUI as soon as | | | | | it is applicable | +--------------------+-------------+---------------------+-----------------------------------------------------------------------------------------+ .. tabularcolumns:: |m{3.5cm}|m{1cm}|m{10cm}| .. table:: Child elements available for all input descriptions. :align: center :name: tab-19 +--------------------------+-------------+---------------------------------------------------------+ | | | | | Name | Required | Description | +==========================+=============+=========================================================+ | | | | | exsite_description | no | Relative path to an html description of the | | | | input object | +--------------------------+-------------+---------------------------------------------------------+ | | | | | exsite_default | no | Default value for this input object (Value | | | | must be valid in the context of the type attribute.) | +--------------------------+-------------+---------------------------------------------------------+ | | | | | exsite_required_position | no | Used when input object is required in a | | | | certain position (Position counting starts from 0.) | | | | | +--------------------------+-------------+---------------------------------------------------------+ | | | | | exsite_summary_line | no | A short description used in the GUI | +--------------------------+-------------+---------------------------------------------------------+ | | | | | exsite_icon_path | no | Relative path to an icon that can be used to | | | | indicate this input object in the GUI | +--------------------------+-------------+---------------------------------------------------------+ The following values are allowed for the type attribute: **exsite_string:** The input object described by this tag is assumed to be a string. It takes two additional attributes: - spaceAllowed, which can have values of yes and no and indicates whether the string can contain spaces - equalAllowed, which can have values of yes and no and indicates whether the string can contain equal signs **exsite_flag:** The input object describes a Boolean value. If the keyword is present, the Boolean value is set to *true*, otherwise to *false*. No additional attributes or elements are available for this type. **exsite_float/exsite_integer**: The input object describes a float or an integer object. No additional attributes are available. Additional elements available are: - exsite_max_required, which gives the upper bound for the number - exsite_min_required, which gives the lower bound for the number **exsite_key:** The input object describes a bare keyword that has different meanings depending on its value. It is different from exsite_flag since the result value must preserve the actual value given by the user. **exsite_boolean:** An input object that describes a Boolean value. The values *yes* or *true* are both recognized as setting the value to *true*. The values *no* or *false* both set the value to *false*. All other values are not accepted. **exsite_file:** This input object is similar to exsite_string; however, it denotes that this object is a file. The GUI can then display this object with a file selection box. The object has several additional attributes: - spaceAllowed, which can have values of *yes* and *no*; indicates whether the filename can contain spaces. - isNewFile, which can have values of *yes* and *no*; indicates whether the input refers to an existing file or whether it will create a new file. Based on this information, the GUI can determine whether to display a load or save dialog. - substituteDrive, which can have values of *yes* and *no*, and only takes effect if the underlying operating system is a windows system. If set to *yes*, then the drive letter of the default value is changed to the same drive where the Exsite program resides. **exsite_enum:** The input describes an enumeration type of input parameter. It takes one additional optional attribute and several required elements. The additional attribute is allowUser, and it takes a value of *yes* or *no*. If true, users are allowed to add values in addition to choosing one of the predefined options. The required elements are: - enum_type with attribute type. The value of type defines which types of values are allowed for the enumeration. - One or more exsite_enum_option elements listing the available choices. The element contains one additional element named exsite_description, which contains the description of this option. The remaining text is the value of the option. **exsite_array:** An input type describing an array of data. The element contains several optional attributes and one required element. The attributes are: - length giving the number of elements in the array. The value can take the same arguments as the repeat attribute listed in :numref:`tab-18`. The default is exsite_unlimited. - arrayStart character string indicating the start of array values. A value of "\\n" will be substituted by an end of line character. The default is to use no start value. - Separator gives a list of characters that separate array elements. The value "\\n" is substituted by a new line character, "\\t" by a tab character, and "\\r" by a hard return character. - arrayEnd is the same as arrayStart, except it denotes the end of array values. The default is to use no end value. The array terminates after the first character string that cannot be parsed as an array element. - arrayMarkeRequired is used if arrayEnd and/or arrayStart are given but are not required. - lengthAbsolute uses the absolute value stored in length to calculate the desired length of the array. .. In addition, the element takes one required element, array_type with required attribute type to indicate the type of data to be stored in the array. **exsite_close_depend:** An input value that can be used inside a group input element. It is used if group is closed by a certain character string. In some special cases, the occurrence of this character string does not indicate the end of the group input. This is a marker input not displayed in the GUI and depends on the attribute values of the group of which it is a part. This element takes one required attribute endBlockValue, giving the character string that can potentially end the group input. **exisite_group:** an input element that groups together other input elements. The available attributes are listed in :numref:`tab-20`. **exsite_fidas:** This is a special case of exsite_group for use with fidas type input. It describes a fidas array. The readBlockValue and readBlock attributes need to be explicitly given. Like other exsite_group elements, it contains input elements describing the various entries into a fidas array. The input elements can be any of the elements describing numbers of the correct type of the fidas array. .. tabularcolumns:: |m{2.5cm}|m{.8cm}|m{1.5cm}|m{10cm}| .. table:: Attributes available for exsite_group element. :align: center :name: tab-20 :class: longtable +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | Name | Required | Possible Values | Description | +====================+=============+====================+================================================================================+ | | | | | | endBlock | no | yes | Indicates whether the end of the group input | | | | | is indicated by a certain combination of characters If **closeOnRequired** | | | | no | is selected, then the group input is closed if all required input | | | | | elements have been given. | | | | closeOnRequired | | | | | | *Default is no*. | | | | | | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | readBlock | no | yes | Indicates whether the start of the group is | | | | | input, as indicated by a certain combination of characters. | | | | no | | | | | | *Default is no*. | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | canFold | no | yes | If set to "yes." then the group input can be | | | | | folded into the GUI. | | | | no | | | | | | *Default is no*. | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | readBlockValue\* | no | | If **readBlock** indicates that a certain character combination | | | | | starts the group, this attribute gives that character combination. | | | | | The value \\n is substituted by a new line character. | | | | | There can be more than one character string that opens | | | | | the group. If so, they must be supplied in more than one instance | | | | | of readBlockValue. Since XML only allows unique attribute names, | | | | | substitute \* with any value to make the attribute name unique. | | | | | | | | | | *The default is read *. | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | endBlockValue\* | no | | If endBlock indicates that a certain character | | | | | combination ends the group, this attribute gives that character combination. | | | | | | | | | | The value \\n is substituted by a new line | | | | | character. There can be more than one character string that ends the group. | | | | | If so, they must be supplied n more than one instance of endBlockValue. | | | | | Since XML only allows unique attribute names, substitute \* with any | | | | | value to make the attribute name unique. | | | | | | | | | | *The default is end *. | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | matchTag | no | yes | If there is more than one value for readBlockValue | | | | | and endBlockBalue, then ensure that matching pairs are used. | | | | no | Pairs are generated by order of appearance in the xml file. | | | | | | | | | | *Default is no*. | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | xmlOrder | no | yes | If set to "true," the order of the elements in | | | | | the input file must be the same order as given in the xml description. | | | | no | | | | | | *Default is no*. | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | discardBlockEnd | no | yes | If set to "true," the group is terminated | | | | | after the endBlockValue is read. However, the character | | | | no | string is not consumed and thus is available for parsing | | | | | for the next input element. | | | | | | | | | | *Default is no*. | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | noEmptyOnDiscard | no | yes | If set to "true," a group can consist of no | | | | | input elements in the input file. Otherwise, an empty group is flagged as an | | | | no | error. | | | | | | | | | | *Default is yes*. | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | closeDepends | no | | The name of the field is defined here if the | | | | | endBlockValue is present but does not indicate the end of the group unless a | | | | | certain field is set (The parser will automatically create a field of type | | | | | exsite\_close\_depend. This input type needs to be defined in the xml input | | | | | description.) | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | closeDepend\ | no | | If closeDepends is set, | | CompValue | | | the value of the field given in closeDepends that keeps the group open | | | | | | | | | | | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ | | | | | | closeDepend\ | no | | If closeDepends is set, | | Compare | | | the means to compare the field | | | | | | | | | | | +--------------------+-------------+--------------------+--------------------------------------------------------------------------------+ .. _compare-examples: Examples ~~~~~~~~ The following example is the input for the compare module, which uses FIDO style input: :: MODULE TO COMPARE FUNCTIONS ON TWO TAB1 FILES Centrm parameters 0 1 Number of words of core to allocate. 500000 Logical unit on which the first TAB1 File is located< 1 Logical unit on which the second TAB1 File is located 2 Logical unit where the difference TAB1 File 3 The element compare gives the name of the module and indicates that an end block is required, and it consists of end on the start of a new line. The centrm element is required for almost all modules. It indicates that all input following the name of the module until the end of the line is to be read into the input element centrm and to be hidden from the user. The input consists of one block of data terminated by the customary "t" at the end of the fidas block. This is defined in the element named x_1. The input consists of one fidas array (``-1$$``) which is described in the element named Core_Allocation. It indicates that the fidas array start after the character string ``-1$$`` is found. The fidas array group closes automatically if all children have been given. The attribute value for noEmptyOnDiscard indicates that the group fidas array can be omitted if all default values are desired. Finally, all the input elements are listed. They are all of type exsite_integer and need to appear in the same order as given in the xml description. .. _template-files: Template Files ~~~~~~~~~~~~~~ Template files to be used in ExSite are a combination of user input descriptions and templates used to generate input files. They consist of two sections. The first section contains an input description as used for module input description. It contains input parameters needed to execute the template. The second part consists of a template using a selected XML listing and the parameters supplied in the first section. The first section is an input description for keyword-based input. In addition to the fields supplied by the input description, the program automatically adds descriptions for: - "evals," an input field that takes file name of the file containing the XML listing of the abbreviated ENDF information - "input," an input field that describes the name of the input file to be created - If the input description contains a field named "neutgroups" and a field called "thermalgroups," a field name "iftg," denoting the first thermal group, is automatically created. In the template the fields of the user input are available in two ways: - A postfix of "_user" is added to list of arguments available to the writeData function listed in :numref:`tab-15` and :numref:`tab-17` - XML entities are added to the template created. XML entities can be accessed in an XML file by using "&entity;". Common examples are the entities normally provided for the ampersand and the lesser than sign, "&" and "<" respectively. However, since the template in given in Exsite template file does not have these values defined, "entity_fieldname" is used, which will be translated to an entity reference if expanding the template. writeData applies to the data for a given evaluation. Therefore, writeData only works inside a loop. On the other hand, entities are available throughout the template. In addition, if an input field of type "exsite_array" is encountered, additional user fields are created: - fieldname_number contains the number of fields in the array - fieldname_strip creates a list of the array with array markers, commas and end of line values stripped and substituted by spaces - fieldname_eol is the same as fieldname_strip, except instead of a space an eol is used There are two types of ExSite templates: one that gives a template, and one that uses previously defined templates. The later allows the user to string previously defined templates together. Inside the root element, which can have any desired name, the first type of template has two elements: - An element named *InputParameters* that contains the description for the user input. It is structured like a module input description. - An element named *InputData* that contains the template to be used. The following example creates a tabular list of all the evaluations (line numbers are not part of the template): .. code-block:: :linenos: Create a table of the xml data. Centrm parameters 0 yes yes no Do you want to list the gamma data
Tag name endf scale id yield gamma eval ---------------------------------------------------------- writeData(tag,10) writeData(endf,10) writeData(changedza,10) yes no writeData(taggamma,10) Tag name endf fast tag fast endf scale ID has yield gamma eval ---------------------------------------------------------------------------------- writeData(tag,10) writeData(endf,10) writeData(tagfast_thermalNum,10) writeData(endffast_thermalNum,10) writeData(changedzathermal_thermalNum,10) yes no writeData(taggammathermal_thermalNum,10) .. The first element (InputParameters, line 5--28) lists parameters under the user control. The user can select whether the associated gamma evaluations should be listed. The second element (InputData, line 30--104) lists the template. The input file is opened on line 32. Please note that the "entity_input" type of referring to user input must be used here. The form "writeData(input_user)" will only work inside a loop. Line 35--37 writes the first part of the title. The text elements must be enclosed in a writeFile element, and "entity_input" type of referring to user input must be used outside a loop construct. The title should contain a reference to the gamma evaluation only if the user requests it. This is done with the exclude element in line 39--43. Inside a loop construct the more convenient restrict attribute for the text element could have been used. The loop element in line 53--63 writes the data for non-moderator evaluations. The restrict argument is used to restrict the loop to evaluations pertaining to incident neutrons and containing File 3 data but no File 7 data. Lines 54--55 are used to write out quantities available for all evaluations. Line 56 prints a yes if the evaluation contains photon production data. An evaluation contains photon production data if AWP0 is yes or if it contains File 12 or File 13 data. Since neither of the restrict arguments is prefixed by a "+,"evaluations are selected for which AWP0 is yes and/or which File 12 and/or File 13 exists. Line 56 prints a no if no photon production data exist. The "-" before each of the restrict arguments should be marked. Lines 68--69 print the tag name of the associated gamma evaluation if the user requested it and if an associated gamma evaluations exists. Lines 65--104 repeat the same tables, but they only select thermal moderators. In order to print all associated evaluations in the fast range, a thermalLoop construct is used in lines 84--103. The postfix "fast_thermalNum" that appears on many of the quantities refers to the desired quantity in the evaluation to be used in the fast region. The postfix "gammathermal_thermalNum" selects the gamma evaluation associated with the fast evaluation. .. !please check Line callouts above. Thanks! Additional examples can be found in the exsite folder, which contains templates to create all the major library types. .. _generating-mod-pdf-input: Generating Module Input and PDF Input ------------------------------------- Input instructions for modules are automatically translated from information supplied in the file containing the main program for a module. The comments are given in lines starting with "!!\*" for Fortran files and "\*!!" for C or C++ files. All lines starting with this special comment character are extracted and interpreted as an XML file.