FitsGeo -- Python package for PHITS geometry development and visualization
FF ITS G EO — P YTHON PACKAGE FOR
PHITS
GEOMETRYDEVELOPMENT AND VISUALIZATION
A P
REPRINT
Ivan Gordeev
Joint Institute for Nuclear ResearchDubna, Moscow region, 141980, Russia [email protected]
August 11, 2020 A BSTRACT
An easy way to define and visualize geometry for PHITS input files introduced. Suggested FitsGeoPython package helps to define surfaces as Python objects and manipulate them conveniently. VPythonassists to view defined geometry interactively which boosts geometry development and helps withcomplicated cases. Every class that sets the surface object has methods with some extra properties.As well as geometry generation for PHITS input, additional modules developed for material and celldefinition. Any user with a very basic knowledge of Python can define the geometry in a convenientway and use it in further research related to particle transport.
Keywords
Python · VPython · PHITS · Geometry Setup · Monte Carlo Modeling · Particle Transport
Every Monte Carlo (MC) transport code such as MCNP [1],FLUKA [2] or PHITS [3] have a part with geometry con-struction. This part of work with MC codes usually isthe most time-consuming and require some concentrationfrom user. Usually, the geometry preparation representswriting some lines (commands) with specific for transportcode formatting in so-called “input file”. Full process ofgeometry setup can be defined in 3 steps:1. Materials definition.2. Surfaces definition.3. Cells definition.Each step has its special “section” in the input file. Onthe first step, the materials section must be defined, whichdescribes certain materials (e.g. water, void and so on)for future geometry objects. In the second step, the userdefines basic primitive objects — surfaces, such as planes,spheres, boxes, cones and so on. Defined surfaces latercan be combined together in some way to represent “cell”(in MCNP and PHITS) — more concrete physical volume,with certain material, which also defined in other specialsection on the third step of geometry setup. Through thesecells transport of particles will go during program execu-tion. And in these cells some physical quantities (energy deposition, flux, yield, etc) of radiation scored in so-called“tallies” (another special section).Visualization of the geometry construction process is anextremely necessary thing, which is somehow providedby the MC codes. One of them, for example, FLUKA,provides special graphical user interface (GUI) — Flair [4]written in Python. Flair is a powerful tool for creating inputfiles. In this interface, the user has an almost pure CADsystem (based on the “flair-geoviewer” C++ library), so thepart of the work related to configuring the geometry setupbecomes easier, since every defined object is displayed in3D and can be changed interactively. This 3D visualizationhelps to avoid mistakes and typos when configuring thegeometry.Other codes, such as PHITS, have only limited features forvisualization. PHITS uses ANGEL software that createsEPS (stands for Enhanced PostScript) files from PHITSinput file. This means that the user cannot get a pureinteractive 3D image of the created geometry and for visu-alization purposes only has eps files where the geometryis displayed from one perspective (see Figure 1 for an ex-ample of such visualization). In other words, every timea user wants to see what his current geometry looks likefrom all sides, one need to change the “camera” settings,re-launch PHITS in 3D creation mode, and look at thegenerated eps image, for another perspective other settings a r X i v : . [ c s . H C ] A ug itsGeo — Python package for PHITS geometry development and visualization A P
REPRINT are needed, and this process can take some time and causeinconvenience. And this visualization is not interactive (nozooming, no rotating, no panning), so the user can’t just “fly” through the geometry setup and look at each side ofcreated geometry.Figure 1: The “Snowman” example. PHITS geometry visualization via ANGELAlso, if one need to create a really complex geometry witha lot of objects, it is just very difficult to remember all theparameters and set them accordingly by hand every time,not to mention appearing typos while this process. Though,in PHITS user can specify variables, but this helps onlypartially.These problems with poor visualization and quite compli-cated geometry setup by hand encouraged to make a toolthat makes this specific part of work with geometries eas-ier and more illustrative. FitsGeo can help the user focusmore on a concrete geometry by providing high-quality3D visualization using VPython and automated generationof geometry objects to PHITS understandable format. Theobject-oriented programming (OOP) paradigm is a pow-erful way to prepare such input files, which opens up newpossibilities for configuring geometry.FitsGeo can be very helpful for all researchers workingin the field of particle physics, shielding, accelerator de-sign, radiation safety, and other fields of applied physicsin which MC transport codes (so far only PHITS) are acommon tool. Furthermore, some additional features areprovided with the definition of other sections (material andcell sections). The object-oriented way to define geometry and other sections of input files has much more possibili-ties and provides more flexibility for the user. In addition,this package can be the basis for future development of theGUI for PHITS.
FitsGeo is a Python package with a set of modules. Eachmodule provides a specific set of classes and some addi-tional functions that a user with very basic Python knowl-edge can use to create a Python script file for configuringgeometry. The object-oriented way of creation of geome-try surfaces and additional sections for PHITS input filesmeans that all defined surfaces, materials, and cells arePython objects with some additional properties (get andset methods) such as volume, surface area, density and soon. Thus, the user can change these objects “on the fly”when coding geometry. Each object has a number of get-ting and setting methods, which provides more flexibilityfor the user. GitHub repository of project — https://github.com/GordoNice/fitsgeo.git
A P
REPRINT
Modules in FitsGeo Package: • material module handles material definitions: ma-terials for geometries can be set from predefineddatabases or manually; • const module consists of constants used in Fits-Geo: colors for surfaces as VPython vectors andANGEL colors associated to these colors (in thePython dictionary); • surface module consists of classes for definingsurfaces — this is the main class which providesvisualization functionallily of FitsGeo; • cell module consists of class to define cells; • export module provides functionality for export-ing all defined objects to the PHITS understand-able format (other MC codes may be added in thefuture releases of FitsGeo). Additional modules for other sections of PHITS input, suchas the source definition module will come soon.Being a Python package, FitsGeo requires Python inter-preter. To work with FitsGeo user need to install it first(via pip tool), create Python script file and import Fits-Geo package in the script. After these simple steps, fullfunctionality of FitsGeo is available. From now on, everyaspect with geometry setup can be set as Python object. For the full user guide and examples of using FitsGeo,see the FitsGeo documentation . Only one example is dis-cussed here, called “Snake” (Example 2(b): Snake! on thewebsite). The full code for this example is shown in theFigure 2.Figure 2: The full code of FitsGeo Example 2(b): Snake!This example demonstrates a workflow for creating multi-ple (repeating) objects whose placement and size dependon certain mathematical laws. The geometry consists ofsphere-segments of the snake’s body. Each part of thesnake’s body defined according to certain math laws forposition and size. The example can be divided into 5 parts:1. Definition of math laws for positioning and sizingof snake’s parts (lines ).2. Definition of materials (lines ). 3. Definition of surfaces (lines ).4. Definition of cells (lines ).5. Geometry draw and export of all defined objectsto the PHITS input file as specific sections (lines ).Before the actual definition of geometry, the user mustimport modules (lines ). In line , FitsGeo package im-ported with fg alias. Additional functions from the NumPypackage are imported for mathematical expressions. FitsGeo documentation website — https://fitsgeo.readthedocs.io
A P
REPRINT
The first part of the code in the above list uses the NumPymodule to set mathematical laws of positioning and sizingof snake segments. Let’s assume that this snake consists ofsphere-segments that must be arranged according to somemathematical law. Assume the following equation for thepositions of the sphere-segments on the xz -plane: z ( x ) = 5 · sin(3 x ) · . − . x ) (1)This is a formula for z coordinates, where for x coordi-nates we take 50 evenly spaced numbers from 0 to 5. Andon the y coordinate it is 0 everywhere. The graph for thisequation is in the Figure 3.Figure 3: Mathematical law for the positions of sphere-segments of a snakeThe equation for the radii of the sphere-segments: r ( x ) = 0 .
02 exp(0 . x ) (2) This law will give us a slow exponential (almost linear)increase in the radius of the sphere-segments dependingon the x coordinate. The graph for this law is shown in theFigure 4.Figure 4: Mathematical law for the size of the radii of sphere-segments of a snakeUsing FitsGeo, sphere surface objects are placed on pointsaccording to the law from the Equation (1) and with radiiaccording to the law from the Equation (2). This showswhy an object-oriented way of defining surfaces can beuseful for such geometries. The second part of the code defines materials for the ge-ometry from predefined databases. FitsGeo has databaseswith more than 500 predefined materials adapted fromGEANT4 and SRIM MC codes. In this example, the“ICRP skin” and “Polyethylene” materials were initialized. Official website of Geant4 Collaboration — http://cern.ch/geant4 SRIM official website — http://srim.org/
A P
REPRINT
The third part of the code creates geometry surfaces(sphere-segments of the snake and a hat on the head ofthe snake). Here, the flexibility of FitsGeo becomes moreclear, because the user can place surface objects relativeto other objects, so the user can even place a hat on thesnake’s head. It is noticeable that such manipulations isunlikely to be achieved without FitsGeo.The fourth part of the code is responsible for definingcells. Here we see another advantage: the user can definecombinations of surfaces using their names, rather thannumbers, as is the case in PHITS. Cells are defined bytreating regions divided by surfaces. Surface classes inFitsGeo have overloaded Python operators “+” (__pos__)and “-” (__neg__), which makes it possible to define “sur- face sense”. These operators return the numbers of thesurface objects as strings.Finally, the fifth part of the code is responsible for thevisualization and exporting. In each object method, theuser can pass additional parameters (flags) for optionaladditional functionality, such as changing the opacity ofthe surface, putting labels that point to the center of thesurface, or exporting only certain sections to the PHITSinput file, and so on. After executing the “draw” method ofthe surface, the browser tab opens automatically, and theuser sees the created geometry in 3D and can interactivelyview it. This visualization is based on the VPython. Thescreenshot of such visualization is in the Figure 5.Figure 5: Geometry visualization of FitsGeo Example 2(b): Snake!The sections exported to PHITS are shown in the Figure 6.This is generated automatically, obviously it is very dif-ficult to create such a geometry manually using only the standard way. After export of these sections to the inputfile, user can perform standard visualization in PHITS viaANGEL (see Figure 7).Figure 6: The exported from FitsGeo sections for the FitsGeo Example 2(b): Snake!5itsGeo — Python package for PHITS geometry development and visualization
A P
REPRINT
Figure 7: Standard visualization of the “Snake” example in PHITS via ANGEL
A new way to configure the geometry for PHITS input fileshas been introduced. The described way has certain ad-vantages, such as an object-oriented way for determiningsurfaces, materials and cells, improved interactive visual-ization (using VPython), and automatic export of definedsections to the PHITS input file.The main features of FitsGeo: • Great visualization capabilities with VPython. • Easy geometry setup. • Python and the OOP paradigm provide more flex-ibility for geometry development. • Additional properties for each type of definedsurface (volume, surface area, etc). • Databases with 500+ predefined materials. • Export of defined objects as sections of the PHITSinput file. • FitsGeo is well documented and simple even fora beginner in Python.The tool is suggested to be used for a certain group ofresearchers engaged in MC modeling of particle transport.The described features will certainly improve geometrydevelopment for researchers working with PHITS (exportto other codes may be done in future releases). With thispackage, researchers can be more focused on the mosttime-consuming part of work with PHITS. This will lead to faster development and less mistakes during the geome-try configuration stage.
The “FitsGeo” Python package is presented. This pack-age can be a really useful tool for those who works withPHITS code and need more degree of freedom in devel-oping geometry and visualization. A set of modules withclasses and functions make it easy to configure the geom-etry. Surfaces, materials, cells can be set up as Pythonobjects with all the advantages that follow, they are easy tovisualize, and the user can easily export them to a formatthat is understandable for PHITS. The FitsGeo package iswell documented and has a bunch of usage examples, soeven a user who is far from programming can easily startdeveloping the geometry and use it for further research.6itsGeo — Python package for PHITS geometry development and visualization
A P
REPRINT
References [1] C. J. Werner, J. S. Bull, C. J. Solomon, F. B. Brown,G. W. McKinney, M. E. Rising, D. A. Dixon, R. L.Martz, H. G. Hughes, L. J. Cox, A. J. Zukaitis, J. C.Armstrong, R. A. Forster, and L. Casswell. Mcnp6.2release notes. 2018. Los Alamos National Laboratory.[2] A. Ferrari, P. R. Sala, A. Fassò, and J. Ranft.
FLUKA:a multi-particle transport code . CERN, Geneva, 102005. Work supported by Department of Energy con-tract DE-AC02-76SF00515, INFN/TC_05/11, SLAC-R-773. [3] Tatsuhiko Sato, Yosuke Iwamoto, Shintaro Hashimoto,Tatsuhiko Ogawa, Takuya Furuta, Shin ichiro Abe,Takeshi Kai, Pi-En Tsai, Norihiro Matsuda, HiroshiIwase, Nobuhiro Shigyo, Lembit Sihver, and Koji Ni-ita. Features of particle and heavy ion transport codesystem (phits) version 3.02.
Journal of Nuclear Sci-ence and Technology , 55(6):684–690, 2018.[4] Vasilis Vlachoudis. Flair: A powerful but user friendlygraphical interface for fluka. In