Xcoll release 0.9.0

What's Changed

General

• Updated LossMap with a few new features and to make interpolation=False work correctly (automatic calculation of the correct length). The height normalisation in plots is now correct (though the bar width should be adapted to represent the length between two consecutive apertures).
• Removed CrystalMaterial; all are now instances of Material only (except RefMaterial).
• Added align_to_beam_divergence to line.collimators API for crystal tilt alignment

Interface to FLUKA

(#78, #80, #83, #86, #120, #91, #131, #132, #138, #139, #152 by @freddieknets, @andredonadon, @luillo76)

• Prerequisite: Need a complete installation of FLUKA with its LineBuilder and FlukaIO. Then compile the interface with xcoll.fluka.environment.compile() while providing either the source with flukaio_path or the pre-compiled library with flukaio_lib (this needs to be done only once). For compilation, the meson package is needed (which can be found on conda-forge).
• New elements FlukaCollimator and FlukaCrystal which work exactly like an EverestCollimator or EverestCrystal but with FLUKA physics. An important addition is that FLUKA uses geometric definitions for its elements, called FlukaPrototype (if it is a single body) or FlukaAssembly (if it is made from multiple bodies, like a collimator that has two jaws and sits in a cryogenic tank). In both cases, this is assigned to the collimator by its assembly attribute.
• As the protoypes/assemblies can be quite complicated to manage, the accessors xc.fluka.assemblies and xc.fluka.prototypes are provided to inspect all protoypes/assemblies known to Xcoll. If a FEDB (Fluka Element DataBase) is provided, it can be imported with xc.fluka.environment.import_fedb(fedb_path, verbose=False, overwrite=False). To make a custom definition, the correct files have to be generated (see https://gitlab.cern.ch/bmi/fedb/coupling/linebuilder/-/blob/master/README.md), the definition created with assm = xc.FlukaAssembly(...) or prot=xc.FlukaPrototype(...) and the generated files assigned as assm.assembly_file = filename, or prot.body_file = filename1, prot.region_file = filename2, and prot.material_file = filename3which then will copy these files to Xcoll's internal database. For easier scenarios, a FlukaCollimator can be specified without providing anassemblybut by specifyingmaterialandlength(and optionallyside`), in which case a temporary generic assembly is generated.
• An prototype or assembly can be inspected with Flair using coll.assembly.view() (or xc.fluka.assemblies['...'].view() etc), while all geometry to be tracked can be inspected after starting the engine with xc.fluka.engine.view().
• As FLUKA has its internal definition of particle masses, these might sometimes differ from Xsuite's. When the difference of the reference particle mass is too large, this can lead to an accumulation of numerical error. It is for this reason that, when starting the engine, the mass of the reference particle is temporarily overwritten (also in the line) by the FLUKA value. Hence, one should create the xt.Particles object after starting the engine to avoid being out-of-sync. All FLUKA masses known to Xcoll can be inspected with xc.fluka.particle_masses.
• If ever needed, the naming of particles in FLUKA can be inspected with xc.fluka.particle_names .
• Before scattering can be active, a connection to FLUKA needs to be made. This is done by starting the engine: xcoll.fluka.engine.start(). For this, the necessary arguments are either elements or line to specify which elements are to be linked (with the additional optional argument names if it is only a subset), and particle_ref to describe the beam if not already provided by the line (and in case the line has a different reference particle, this is overwritten by the engine's one and restored when the engine stops). Optional arguments include:
  • seed to set the seed in FLUKA
  • cwd to define a run folder (a random named one is generated by default for the logs etc)
  • clean to clean up connection and log files
  • capacity to specify the maximum number of particles transferred to FLUKA (it is the user's responsibility that this is the same as the capacity in the particles object)
  • relative_capacity to auto-size the capacity for efficiency, based on the number of particles that hit (for protons with default physics return settings, relative_capacity=2 is adequate; when all particle types are returned, relative_capacity should be at least in the order of a few hundreds
  • verbose to print out info during the connection setup and input file generation
  • timeout_sec to control how long the interface will wait for a reply from the server before considering it dead (typically not needed to adapt)
  • fortran_debug_level to control the level of debug information that is printed out from the FLUKA server's side
  • touches to create a file with the FLUKA touches (used as input for follow-up deposition studies in pure FLUKA)
  • prototypes_file and include_files to manually control the generation of the input file (not trivial as mistakes are difficult to spot)
• Physics settings:
  • return_photons, return_leptons, return_electrons, return_muons, return_tauons, return_neutrinos, return_baryons, return_protons, return_neutrons, return_other_baryons, return_mesons, return_pions, return_kaons, return_other_mesons, return_ions: Individual flags to define which particle types to return. Where possible, this also limits these particles in the FLUKA calculation itself, strongly decreasing CPU time. Sensible defaults are defined base on the reference particle.
  • return_all, return_all_charged, return_neutral, return_none: These are modifiers that can be combined. E.g. setting return_none=True, return_neutral=True, and return_pions=True, will only return pi0s.
  • hadron_lower_momentum_cut, photon_lower_momentum_cut, electron_lower_momentum_cut: Particles with momenta larger than these cuts will be instantly killed off in FLUKA.
  • All settings can be inspected with xc.fluka.engine.physics_settings().
• Note that engine attributes can be pre-set on the engine before starting. In that case, they keep their value even after stopping the engine (within the same Python session). Otherwise, they are reset to their defaults after stopping the engine.
• FLUKA uses an input file with the geometry definitions and physics settings. This is auto-generated based on the options above, though, for full flexibility, a user-provided file can also be passed to the engine with the input_file argument. Note that, to ensure a certain input file is compatible for the set of elements passed to the engine, the input file has an Xcoll header (as comments) with relevant info of the elements. As it is not trivial to manually generate this header, a function xcoll.fluka.engine.generate_input_file() is available to create the input file (including the header) based on a line or set of elements, which can then be manually adapted to the user's wishes before using this file to start the engine. It takes the same arguments as xcoll.fluka.engine.start() with the additional optional argument filename.
• The material definition of an element is governed inside Xcoll, and the correct code to define it in FLUKA is auto-generated. If a material already exists in the built-in FLUKA databases but not in Xcoll's, there are two options:
  • Define the material in Xcoll the standard way, and set the attribute fluka_name to the correct name (case-sensitive). This will essentially ignore the Xcoll parameters and use the material definition in FLUKA. It is the user's responsibility to make sure both definitions represent the same to avoid misunderstandings.
  • Use a ReferenceMaterial which has no properties except fluka_name. This is preferred, as it is clear that no Xcoll definition is used.
• See the examples for more info.

Develop Updates

• Bugfix in material: When loading from dict a material that already exists in the db (and which is equal), return the db one (to have memory identity). Also fix in generic assemblies which, if the material does not exist in FLUKA code yet, should not store the fluka_name in the assembly metadata.
• Engines no longer os.chdir but run deferred in cwd folders (except the creation of the FLUKA input file ,which needs to temporarily move into the run folder)
• Cleaned up Constants code and added str constants type.
• Streamlined tetst to select FLUKA or Geant4 (or Everest) tests with pytest -m fluka etc, and automatically skip if the environment is not ready/compiled.
• LossMap: Added stricter versioning, beam_type, and __eq__.
• Updated examples:
  • Engine should stop AFTER making loss map to store the correct reference particle.
  • Added high-statistics examples and stored the output and plots in git.
  • Update LHC example lines to have collimation metadata, and updated loss map examples.
  • Added example comparing energy definition of all three scattering codes (Everest, FLUKA, Geant4).
• Created a function deep_equal to compare two lists/arrays/dicts/objects in any nesting level (meant as an improvement on line._dcts_equal in Xtrack).
• Created a PhysicsSettings class (always present as an attribute of the engine) to manage all physics settings cleanly.
• Fix in loss map plotting; cold/warm regions were something represented wrongly.
• Fix in BaseCollimator: allow tilts to be set to None.

New Contributors

• @andredonadon made their first contribution in #78
• @luillo76 made their first contribution in #152

Full Changelog: v0.8.0...v0.9.0