Tools for Fluka Studies

The tools presented in this Twiki web page mainly involve the simulation framework for accelerator studies and the collection of available models of accelators. This does not exclude that tools or solutions presented here may be useful to Fluka users in other contexts.

All the tools are stored in dedicated svn repositories, as svn offers an optimal platform for tracking changes and propagating updates. All the svn repositories are located at:

clueet.cern.ch:/home/SVN_Repository

Because of the wide use of svn repositories, the users are invited to profit as much as possible from svn, and especially to commit all changes that can possibly improve their work in the future, but also the one of current colleagues or those coming after. Moreover, as there is no actual librarian of all the repositories (but for LB) but all the users are invited to commit their changes, it is extremely important to be aware of the consequences of each commit - e.g. do not possibly commit "temporary solutions" if these are likely to be stable configurations. As a rule of thumb, common sense and personal commitment set optimal guidelines for properly committing changes and keep the repositories properly.

Simulation Framework for Accelerator Studies

The simulation framework for accelerator studies consists of a collection of tools aimed at simplifying/improving the generation of Fluka .inp files for beam-machine interaction studies, and their use in producing results. It allows every user to benefit from the work of previous colleagues, especially those working on the LHC machine, and to contribute with personal initiative as far as improvements can be of interest for others.

The framework is factorised in complementary projects, and range from pure Fluka geometries to configuration files and pre-/post-processing scripts. It is mainly composed by (see picture below):

• the Fluka Element Data Base (fedb): a collection of Fluka models of accelerator devices (single collimators, magnets, masks, dumps...), mainly of LHC, SPS-to-LHC transfer lines, SPS, PS, AWAKE;
• the Line Builder (LB): python program for assembling complex Fluka geometries of beam lines. The geometry thus created is based on fedb elements, twiss files and customisation directives from the user. The program is factorised in modules, so that libraries can be imported in other python scripts;
• a chain of pre- and post-processing tools, together with collections of configuration files/settings. In particular:
  • scripts : scripts for generating the final Fluka .inp file, submitting it to the EET batch queue system and analising the output;
  • src : collection of fortran routines for building the Fluka executable for specific tasks, e.g. for implementing magnetic fields, loading loss maps on collimators, simulating beam-gas interactions... Related files of common use are also included, e.g. field maps of LHC magnets;
  • Include_Files : repository of files to be included in the final Fluka .inp file, with some predefined settings for specific tasks, e.g. cut-offs for energy deposition simulations, R2E studies, settings of crossing schemes in LHC interaction regions...

Several assets are native to this approach:

• flexibility
  • fedb: ease of modelling accelerator devices, crucial when adding relevant details, or when following the evolution of the design of future components, or when comparing different technical solutions...
  • LB: automatic synchronisation with the machine optics, essential ingredient for sound modelling of the beam line;
• consistency
  • fedb: a common and shared resource where to keep track and monitor implementation details, especially material definitions;
  • LB: protection against wrong settings of the beam line, e.g. misplacements, wrong orientations, mismatches in magnetic fields and collimator apertures…
  • tools: standardisation and harmonisation of source terms, physics settings, cut-offs, analysis... avoiding re-inventing the wheel every time a new person arrives, but welcoming their initiative in boosting its improvement;
• portability
  • fedb: prompt propagation of updates, with improvements being inherited by all the people involved;
  • LB: the last updates of the fedb are automatically used;
  • tools: tracking of relevant customisation settings.

All the above projects are stored in dedicated svn repositories, and some local copies are shared in the common path:

clueet.cern.ch:/home/LHC/Tools

There, the user can find copies of the fedb, scripts, src and LB repositories - thus only the Include_Files repository is not available, as it is not frequently referenced. These common repositories are meant for general use but not for editing: they are useful if the users need them as they are, skipping the problem of keeping personal local copies up to date or duplicating local copies of repositories that are not going to be modified. These common repositories are updated every hour to the latest revision; in addition, any user can force the directory update, running the force_update.sh script in that directory:

cd /home/LHC/Tools
./force_update.sh
cd -

The update will take place within 2 minutes. Please have a look at the local README file, with few hints and the log of the last commit of each repository.

Please, check also the presentation by A. Mereghetti at the EN/STI/EET Section Meeting held on Oct 2012, 23rd for further information on other available tools and the philosophy underneath.

Accelerator Models

The configuration files for properly building the Fluka .inp file of the beam line to be studied are collected in svn repositories, according to the machine and the actual location of interest of the machine. These repositories collect optics, list of fedb elements to be used, typical scoring cards, and tunnel geometries. They represent also the natural place where to locally edit files in order to create the final Fluka .inp file and run it. The available ones are:

• LHC IRs;
• TI2 and TI8 SPS-to-LHC Transfer Lines;
• SPS LSSs.

The user can find also settings of meaningful previous simulations, if colleagues committed them for future reference.

The user is supposed to work on a given project at a time, so it is recommended to check out a local copy of the concerned repository from clueet.cern.ch and to work / edit files in that local copy. It is highly encouraged to use the common local copies of the most important repositories, unless changes are envisaged. The framework is thoroughly useful if all users commit all their relevant modifications, including configuration files of meaningful cases, i.e. cases that it's worth keeping for future reference, and re-generation.

Repository Structure

At first check out, any repository of each machine/region of interest is structured as follows:

additionals/
collimators/
customized_files/
drawings/
loss_maps/
optics/
saved_configurations/
src/
inputcard-example.txt
.template/

The directory structure helps the users in keeping their work space tidy, ordered and clean. At the same time, despite it might appear rigid, dealing with the same directory structure no matter the studied machine helps users in dealing with different machines. Each directory contains a specific set of files:

• additionals : files providing additional / complementary information to the declared PROTOTYPE / ASSEMBLY, e.g. LB rotdefi_file , new non-magnetic elements, change of names to use special PROTOTYPE...;
• collimators : files concerning collimator settings;
• customized_files : files that the user is supposed to modify in order to generate the Fluka .inp file. At first check out, the directory is empty: the configure.sh will take care of filling it with the default files, that the user can then modify according their needs;
• drawings : relevant drawings concerning the machine / point of interest. Keep in mind that drawings specific to elements should be committed to the fedb repository;
• loss_maps : maps of primary particles to be loaded in the simulation as source term;
• optics : collection of machine optics configurations. In general, it is good practice to first commit these optics files to the OPTICS repository, and then include them as an svn external local copy of repositories (please refer to the section about svn for instructions on how to proceed, and to the local README.txt file in the OPTICS repository for hints on how a proper optics file should look like, or how to add a new optics in the OPTICS repository), so that in case of updates, these are immediately inherited for producing a newly synchronised Fluka geometry. On the other hand, for huge machines like LHC, it may be reasonable to isolate only the optics concerning the portion of machine of interest, in order not to waste time whenever the geometry needs to be recreated. In this same path the user should also put any LB auxiliary_file which actually modifies the twiss sequence, i.e. every time position or magnetic settings of elements are changed;
• saved_configurations : directory where previous colleagues may have committed relevant configurations for future reference. It is good practice to have a directory for each specific case. Please, have a look also at the concerned scripts save_configuration.sh and load_configuration.sh , with which the users are expected to save new configurations or load old ones;
• src : local collection of Fluka routines that could be used for specific tasks. The routines here contained should further customize the simulation with respect to those contained in the src repository: thus, try to use as much as possible the routines already present in src repository, and please refer to them;
• .template : hidden folder with default files in input to LB, i.e. BP_profile.txt, TU_profile.txt and prototypes.lbp files (please refer to the LB Twiki page for the meaning and the syntax of these files). These default files instruct the LB on how to build the largest portion of machine with all the available models of accelerator devices. Please, do not modify them unless you extend the portion of beam line built by default (be aware of what you do!);
• inputcard-example.txt : default general file in input to LB and configure.sh ;

How to Create the Project of a New Machine / Point of Interest

There is no codified/coded way to set up the repository for a new machine or a new point of interest; nevertheless, some basic steps can be identified. For the time being, they should be done manually: they deal with creating the svn repository, registering it in docStone, and creating the default files in input to LB . In particular, the steps are:

1. create the svn repository at:
   clueet.cern.ch:/home/SVN_Repository
   by means of the svnadmin create command;
2. add the project to docStone. Please, remember to add also colleagues and supervisors to the list of people involved in the docStone project;
3. check out the empty repository, and manually structure it according to the standard just shown. Please remember to commit the changes;
4. create the default files in input to the LB and commit them to the .template directory. Please, remember also to create the inputcard-example.txt file;
5. add a default optics.

There is no strict rule about sub-structuring the repository of a given machine in regions of interest (typically insertion regions) but common sense. As a rule of thumb, only for very large machines like LHC it is worth fractioning the repository according to interesting points; on the contrary, for all other machines, one repository is more than sufficient.

Everyday Life

The following are just few tips / caveats to keep in mind:

• the LB takes care only of building the geometry, together with setting the magnetic fields according to the magnetic field routine chosen by the user and its interface. All the rest, including beam and transport settings, is under the responsibility of the configure.sh script, or the user themselves, if the machine is a new one or has not been set up yet;
• do not use only geoviewer to check your Fluka .inp file, but visualise it in a text editor, especially in presence of a strange behaviour. The user can either visualise the *.inp file as produced by the LB, e.g. in case of a possible bug in the LB (most likely), or the expanded *_exp.inp file, i.e. the previous file but with all the #include statements replaced by the actual content of the files, in case of wrong settings by the configure.sh (least likely). Another tool useful for checking the *.inp file just produced is fluka.r : run on the *_exp.inp file, the user can verify the lines actually active, in case of nasty nested #if statements;
• always use configure.sh whenever building or re-generating the .inp or the .x (i.e. the Fluka executable);
• always modify customisation files in customized_files directory, and never the final *_exp.inp file. Otherwise, next time the user runs the configure.sh script, the modifications will be lost;
• keep different optics configurations clearly separated;
• to keep things organized, one may choose to create dedicated directories for specific purposes. Such as directories for runs, executables, magnetic fields, analysis, source term, etc. One may also choose to adapt a naming convention for files and directories such that it can be easily followed by another user who wishes to edit and continue with the same project. This will save a lot of time preparing or debugging the project;
• to save some disk space, one could merge all the USRBIN files from different runs to a single binary file and discard the ASCII file. It is also prudent to keep a copy of the FLUKA input, output, log and error files for future reference;
• including the following line at the top of the file will enable FLUKA color coding in emacs: * -*- fluka -*-

Preliminary Checks

Before actually submitting production runs, it's always useful to perform some preliminary checks, to verify that the Fluka .inp file has been generated in a proper way, and, in particular, the geometry and the magnetic settings are correct. The following basic checks should be thus performed:

1. check the correctness of magnetic fields directions and intensities.
   This can be easily done through Flair, plotting magnetic field lines / intensities superimposed to transverse cross sections of magnetic devices (please, remember to use the Fluka executable with the proper magnetic field routine linked). When checking, please pay attention to:
   1. geometry and magnetic field lines be actually integral, i.e. if the element is tilted, then the field lines should be as well;
   2. effectiveness of field lines. In particular, check that dipole magnetic field lines bend the beam particles in the proper direction, and the quadrupole polarity is correct. Signs of magnetic fields can be directly compared to the magnetic settings in the twiss file - please refer to the MadX manual for sign conventions. Please, take into account the direction of the beam and the right-hand rule when plotting;
2. compare the beam closed orbit computed by Fluka with the one by MadX. This comparison is extremely important whenever a new machine or a new portion is coded in the simulation framework. Here the user can find some instructions;

In general, it is not mandatory to perform all the checks always in the most careful way, but the first time the line is built or when dealing with new portions of machines or a new accelerator. Indeed, the infrastructure has been tested and debugged, thus the generation of the Fluka .inp file is quite robust. Still, it's better to catch surprises before producing strange results.

Other Projects

• OPTICS (link to docStone project - NICE credentials and direct connection to clueet.cern.ch or respective VPN required): repository with the most common optics configurations of LHC, TI2/TI8 SPS-to-LHC Transfer Lines, SPS, PS and AWAKE;
• Coupling: collection of full sets of routines, scripts and configuration files for coupling Fluka to single particle tracking codes for accelerator physics. Trackers available in the repository are: SixTrack, IcoSim, IcoSimpp. This project is somehow independent from the previous ones, despite it is pertinent to the subject.

Flair: Fluka Advanced Interface

flair is an advanced, user-friendly interface for easily editing Fluka input files, running the code and visualising output files/results.

svn

Some hints about svn

• manual and references: the following is a quick reference to most common svn commands:
  clueet.cern.ch:/home/SVN_Repository/Subversion_Quick_Reference_Card.pdf
  whereas this is a more extended on-line manual;
• when committing, avoid the -m option, and give a more extended commit message.
  The commit operation will pop a text editor window with the list of files involved in the commit and the possibility of writing a description of the commit - the first line will be taken as title of the commit message;
• here you can find instructions on how to preset a text editor for svn, useful e.g. when writing extended commit messages, setting svn external properties...
• local copies of svn repositories can be kept also on machines other than the cluster by substituting the URL field from file:/// to svn+ssh://clueet.cern.ch (svn switch command). Remember to be connected to the eet network or the respective VPN network whenever you issue svn commands;
• svn external : the following is a very brief and dirty description of the procedure (it works only if a text editor for svn is set) for setting an svn external repository (for more information about this procedure, please have a look at the svn online manual):
  1. set the svn external properties of the folder in your working copy where to add the external repository:
     /where/I/want/to/put/the/external > svn propedit svn:externals .
     
  2. a file will be opened in a text editor window: fill in the file with a line for each external repository you would like to set, e.g.:
     gaminc svn+ssh://clueet.cern.ch/home/SVN_Repository/coupling/trunk/tools/partdist/gaminc
     
  3. save the file and then svn up the local repository. This operation will fetch the external repository you have just set;
  4. check the settings of the local repository:
     /where/I/want/to/put/the/external > svn propget svn:externals .
     This command will echo all the svn external definitions on terminal;
  5. commit the changes with the usual svn ci method;