Home
!!!! ***** UNDER CONSTRUCTION ***** !!!!
Geometry Description Markup Language (GDML) is a specialized XML-based language used to specify
Geometries for Monte Carlo Simulation software such as ROOT, Geant4, etc see GDML Manual.
It defines a rich set of Solid Computer Graphic Objects for details of GDML Solids
The GDML Workbench lets the user
- Import
- View
- Edit
- Create
- Export
Such Geometries.
From the FreeCAD command bar select View | Workbench then select GDML
It is recommended that when you have the GDML workbench active that the following Toolbars are viewable
- Workbench
- Structure
- GDMLTools
- GDML Part Tools
So Icons displayed should look similar to the following
To make a Toolbar viewable, from the FreeCAD command bar select View | Toolbars
GDML Solids are implemented as FreeCAD Python Objects and have the same properties as defined by GDML. By selecting an Object the properties can be changed via the FreeCAD properties windows and the resulting changes displayed.
Short decription
Short decription
Short decription
Short decription
Short decription
Short decription
Short decription
Given a lot more solids are supported for import, it is not too difficult to add more, so if you feel you need a particular solid to be added please contact me.
Select two Parts/Logical Volumes and then click on the appropriate boolean icon
- Import GDML file
- Scan GDML file - Facility for dealing with large GDML files
When creating a new file from the GDML workbench the file Defaults.gdml is read from the Resources directory, this may or may not have material definitions, as supplied there are none.
A Materials Group called Geant4 is created by reading the file Geant4Materials.xml from the Resources directory which define all the materials that GEANT4 implicitly defines by default.
When a file is exported the default behaviour is to ignore materials in the geant4 groups as GEANT4 implicitly defines these.
If you need the Geant4 materials for use in a none GEANT4 situation, for example ROOT then you can set the Workbench preference to export used Geant4 materials
Any materials in the non Geant4 Group should be exported.
User define materials can be added to a model by importing a xml file with File | Import.
The file needs to be formatted as follows
<xml>
<materials>
...... ( Can contains Isotopes, Elements, Material definitions )
</materials>
<xml>
If you have the materials in an existing cdml file then you should be able to
- Import the GDML file.
- Select the Materials Group
- File | Export
- set a file name and extension of xml
You can then import the exported file into a new model.
We have recently (August 2024) added the ability to create materials from the GDML Workbench. The form can be accessed from the GDML Menu bar, or the icon Add material
The form can be used to add materials in three ways:
-
Enter a material by giving its chemical formula
The compound is built by giving the Element symbol followed immediately by the number of atoms of that element in the compound. Groups of elements can be present multiple times by enclosing them in parenthesis '()' followed immediately by the number of times the group is present. When the Add button is pressed a new material is added to the material group with each element in the forumla present the total number of deduced times.
-
Enter a material from a mixture of pre-existing materials
The material is created by typing a sum of existing materials. The fractions and the material names have to be separated by at least one space and there has to be at least two materials in the sum. Note that the GDML workbench pre-loads Geant4 and NIST materials, so you do not have to create those. The fractions can be written normally (0.75) or using the exponential notation (3.2E-05).
Note that the material name must start with a letter.
The material can also be given as a sum of elements. The pre-loaded Geant4 database already has each element defined as a material (For example, the element Iron (Fe) also exists in the data base as a material named G4_Fe. In the form, however, it is sufficient to give the element symbol.
-
Enter an element by giving its isotopic composition
One can define an element of by giving its isotopic composition. The isotopic composition can be a single isotope: 13C,
or a mixture of two or more isotopes: 0.5 12C + 0.4 13C + 0.1 14C
Note than the isotopes are written with the number of nucleons (N) written first, followed immediately by the Chemical symbol of the element. As in mixtures, there has to be at least one space between the fractions and the isotope symbol. Also note, that for both isotopic mixtures and materials mixtures, the fractions given will be normmalized to 1.0, i.e., the sum of the fractions typed does not have to be 1.0.
The program will do two things when an isotopic mixture is given: (1) create an element from that isotopic composition, and (2) create a material from the resulting element, using the density typed in the form.
Note that the material density should have units mass/volume. The acceptable mass units are: kg, g, mg, and the acceptable volume units are mm3, cm3, m3 (note not mm^3, cm^3, m^3).
In addition to the GDML solids, the GDML Workbench supports the export of a subset of the solids one can create in the FreeCAD Parts Workbench. These are documented below. For those shapes not directly supported for export, the recommended way to proceed is to take the resulting BREP (Boundary Representation) Shape and then translate it to a GDML Tessellate, or use some software like McCad to decompose the BREP Shapes into GDML Objects.
The GDML Workbench provides a number of facilities to
-
Export FreeCAD(BREP) shapes as GDML Tessellated Objects.
-
Allocate a GDML Material and directly Convert a FreeCAD(BREP) Shape to a GDML Tessellated Object
using a number of different algorithms- Standard FreeCAD mesh facilties
- Gmsh
- Tetrahedron (This does not directly translate to GDML, but to a GDML Assembly of GDML Tetra)
Shapes created by the Sketch Workbench and extruded via the Part Extrude command can be exported to GDML. The exrusion must be added to a Part under the worldVol tree. Currently extrusion exports have the following limitations: (1) Arcs/elliptical whose chords are crossed by lines (or other arcs) cannot currently be processed. Arcs/lines that are completely inside or outside other arcs, are supported, though. Examples of Extruded sketches are in Extruded sketches examples
Technical Notes: extrusions are exported as a sequence of booleans of intrinsic GDML objects. BSplines are discretized as a sequence lines and exported as an <xtru solid. The exported xtru can be made smoother (more points) as follows: select the extrusion object, then select its View property Panel. Right click on the Display Options header and check the 'Show All' check box. This will reveal additional properties that can be set. One of them is 'deviation', which defaults to 0.5 (%). Decrease that nummber to get smoother curves. You may increase it to get coarser curves. FreeCAD does not support Deviation values larger than 0.5, but the GDML extruder can use larger values.
Tests comparing the performance of geant simulations with extuded sketches vs their tesselated versions have shown the extrusions to be 2-5 times faster than their tessellations.
Please note that reimporting an exported GDML will expose the constructed booleans so not look the same as the FreeCAD that was exported.
Shapes created by the Sketch Workbench and revolved via the Part Revolve command can be exported to GDML. The revolution must be added to a Part under the worldVol tree. The most recent (2024/08/21) branch of the Workbench allows extrusion and revolves of sketches in any direction from any plane. Revolves around axes other than x/y/z, however, do not resemble FreeCAD revolves. So stick to revolves around the principal axes! The FreeCAD Part revolve allows revolving around an axis away from the origin and this is implmented in the Workbench. Examples of revolved sketches are in Revolved sketches examples
Technical Note: All curves in a revolved sketch, except circles, are discretized and exproted as <polycone's. Circles are exported as a torus. Booleans of these are used to fully construct the revolved sketch. The smoothness of the discretization can be changed as described above, under Extruded Sketches.
Please note that reimporting an exported GDML will expose the constructed booleans so not look the same as the FreeCAD that was exported.
Arrays of objects, constructed under the Draft Array command, or the GDML Array command can be exported as GDML objects. The arrays must be of currently supported objects (GDML, or Part objects, such as extrusions, or revolutions). Arrays of arrays can also be exported. Currently the following types of arrays are supported:
- Ortho(gonal) arrays
- Polar arrays
- Path arrays
- Point arrays
In the future other types of arrays will be supported.
The Array object must be added to a Part under the WorldVolume tree. Note that the array object is exported as a single multiUnion gdml solid. Thus the objects in the array are considered as part of one solid, and hence have one material. It is best practice to assign the material to the Array object. If a material is not assigned to the Array object itself, its (sub)objects are scanned recursivley and the material of the first object that does have a material property is selected.
A mirror of a GDML exportable object (including extrusions, revolutions, arrays) can be created and exported; either using the Draft mirror command, or or the provided GDML short cut. At present the mirrored iobjects (both the original object and its mirror image are exported in a gdml <assembly. They both share the original volume and hence will have the same material. Examples are in Mirror examples. Note that in FreeCAD when a mirrored object is itself mirrored, one only get an additional mirror of the mirrored object, not additionaly a mirror of the original object.
A scaled copy of an exportable object can be exported. The scaling of GDML solids (as opposed to Part shapes, that are not GDML Solids), can be scaled using the Scale Command icon provided with in the GDML Workbench. This command adds a scale property to each of the selected solids; no additional objects are created. In contrast, the Draft scaling operation creates a separate object (must be a clone) that carries the scaling information, while the original object remains in the tree. To export the scaled object, the clone must be added to a Part that is under the WorldVolume tree, while the original object must be outside tha tree (but not deleted, as the clone refers to it). If multiple objects are selected and scaled using the Draft scale operation, all those objects become part of the clone and are exported as GDML multiUnion, and hence will have one and the same material. That material is best assigned to the clone object, but, as in the case of other composite objects, if a material is not provided, the sub-objects will be searched recursively until one is found with a material property, then that material is assigned to the multiUnion. Otherwise a default material (currently G4_STAINLESS-STEEL) will be assigned. A peculiarity of the Draft scale operation is that its placement (rotation and position) are copied from the scaled object, in the case of scaling a single object, and set to the identiy placement in the case of scaling several objects. In either case, the placement property of the clone is its onw and separate from the of the scaled object. Subsequent changes to the placement of the scaled object do not affect the placement of the clone. However, because the GDML Workbench makes use of the original object's placement, changes to those after a scaling operation is performed will affect the exported model, but not the FreeCAD one. Therefore, changing the placement of the original object should not be done after scaling. If it is desired the change the location of the scaled object (the clone), change that placement (not the original), or else delete the clone, move the original and scale again.
The following objects available in the Part Workbench are exported as a gdml tessellation solid:
- Lofts
- Sweeps
- Chamfer
- Fillet
The tessellation of these objects is done automatically, that is, one does not have to make explicit use of the GDML Workbench GDMLTessellate command.
In addition, any object that is created in python as a Part::FeaturePython is automatically exported as gdml tessellation. Examples of these are the objects created by the Fasteners Workbench Fasteners, the Gears Workbench Gears, and the polyhedra created by the Pyramids and polyhedrons workbench Polyhedra.
Examples of the above objects and the view of the exported gdml file
in load_gdml_color are shown in the following pages:
A short study that examines Geant4 simulation timings with tessellated exports vs booleans of intrinsics (GDML) solids can be found here.
To export a GDML file, select the root Part ( GDML World Volume ) then use the standard FreeCAD export facility ( File | Export )
If a filetype of lowercase gdml is selected a single GDML file is produced.
If a filetype of uppercase GDML is selected then the following files are created in a directory derived from the path name less the GDML file extension.
- A [Name].gdml with imbeds for the following xml files
- setup.xml
- constants.xml
- defines.xml
- materials.xml
- [Name]-solids.xml
- [Name]-structure.xml
Note: Provided you have the lxml python library installed, you should be able to successfully open the [Name].gdml file
ROOT only supports GDML defined in a single file, as it does not support the required DOCTYPE !ENTITIES.
There are two options
-
Open the multi file with the workbench and then export with as a single GDML file.
-
Use the standalone python program supplied in Utils
combineGDML.py [input file with imbeds] [output single file]
Such multi files are supported by Geant4.
When exporting STEP files that include GDML objects set the FreeCAD Preference for Export to use legacy exporter
Although we strive to ensure that the exported gdml files reflect the FreeCAD geometry (and vice versa, on import), both FreeCAD and the GDML Workbench are relatively complicated pieces of software and there can be no absolute guarantee that what is constructed in FreeCAD matches exactly what is exported to gdml. However, we have recently added a set of tools to compare the FreeCAD and geant (gdml) geometries. The tools consist of two applications, one that calculates the center of mass and moments of inertia of the FreeCAD geometry and the other does the same for the geant4 geometry read from the gdml file.
The Macro calCenterOfMass.pycalculates the volume, center of mass,
and "moments of inertia" of the selected App::Part (which ought to be
the root, or World Volume).
The geant4 application load_gdml_color displays a gdml file, and, if
an additional option -printCM is given on the command line, also
calculates the volume, center of mass, and "moments of inertia" of the
geometry.
If the outputs for the total volume, center of mass and moments of intertia (from the macro and the geant4 application) match, then almost certainly the geometries are the same in the FreeCAD and in the gdml file (but see discussion below). If the outputs differ, then it is quite likely that the geometries differ, but there might be cases where the FreeCAD and geant4 calculations differ, so the FreeCAD document and gdml file should be inspected carefully at that point.
These utilitites are here:
load_gdml_color Source in directory MH_G4_EXample/MH_G01
Macro's
COG's for directory of FC files
The calculations in both the calcCenterOfMass.py macro and
load_gdml_color application ignore the material of the volume, so,
strictly speaking, they do not calculate the "center of mass", but
rather the center of geometry. The center of each object is weighed by
its volume (rather than mass) in computing the overall "center of
mass". The same goes for the computation of the moments of inertia -
the material/density is not included. What matters is that the
weighing is the same in both the python and C++ computations, so the
results ought to be the same if the geomtery is the same. Note that we
also, deliberately, do not take into account the placement of solids
inside other solids in the computations. So, for example, in computing
the total moment of inertia of a mother logical volume box that
contains a sphere inside it, the moments of inertia of the box is
added to that of the sphere. From a physics standpoint, this is
obvioulsy wrong: the moment of inertia of the box should exclude the
space occupied by the sphere. But we deliberately ignore that because
we want to provide a measure that takes into account the
position/orientation of each object. So, in this example, and since we
take the density of all objects to be the same, the physically
"correct" moment of inertia will not depend on the position of the
sphere inside the box, but the "incorrect" sum will, and that is what
we are after - a measure of the geometrical distribution of objects in
both the FreeCAD and gdml files.
FreeCAD provides a property called MatrixOfInertia for most of its
shapes. That is the property we use for the moments of inertia. For
shapes that do not have the property, we convert the shape to a meshed
solid and then use its MatrixOfInertia property. The converted solid
is not added to the document. Geant4 does not have methods that give
the center of mass or the moments of inertia for its solids. Rather
than provide analytic expressions for the 20 or so odd solids that
Geant4 supports, we use a Monte Carlo simulation for each solid to
estimate the center of mass and moments of inertia. By default the
number of events for each solid is 1,000,000, but that can be changed
by giving a command line argument -logNsim=[3|4|5|6|7|8] where the
argument is power of 10 of the number of desired simulations for each
solid. So -logNsim=3 will use 10^3=1000 events, etc.
The use of Monte Carlo in load_gdml_color necessarily limits the accuracy of the calculations on the geant4 side, so keep that in mind when comparing the FreeCAD and geant4 center of mass/ moments of inertia results.
Another possible difference between the FreeCAD and geant4 results stems from the fact that some of the exported geometries make use of discretization of the exported curves, so the generated surfaces will have slightly different shapes in the exported gdml file than they do in FreeCAD. Geant4, for example, does not have built-in B-splines in the gdml standard, so we have to discretize those curves when exporting to gdml. The acuracy of the discretized can be changed as described elsewhere in this document.
Yet another item to pay attention to is that for large geometries the total volume/center of mass/moment of inertia, might be insensitive to the position/rotation of some small part in the geometry. Both the python script and C++ application produce calculations for each item in the geometry so one might be able to check the results part-by-part. However, there is not a one-to-one correspondance between the FreeCAD and gdml geometry trees, so occasionaly some items might not appear in both, but the totals should include all items.