diff --git a/Documentation/gh-pages/source/element_kassiopeia.rst b/Documentation/gh-pages/source/element_kassiopeia.rst index f5c39043..0d588fd0 100644 --- a/Documentation/gh-pages/source/element_kassiopeia.rst +++ b/Documentation/gh-pages/source/element_kassiopeia.rst @@ -1,6 +1,6 @@ .. _Kassiopeia-element: -Kassiopeia element +Particle tracking - ==================== .. contents:: On this page diff --git a/Documentation/gh-pages/source/element_kemfield.rst b/Documentation/gh-pages/source/element_kemfield.rst index a6a225c5..915fb223 100644 --- a/Documentation/gh-pages/source/element_kemfield.rst +++ b/Documentation/gh-pages/source/element_kemfield.rst @@ -1,6 +1,6 @@ .. _KEMField: -KEMField - field definition +Field definition - =========================== diff --git a/Documentation/gh-pages/source/element_kgeobag.rst b/Documentation/gh-pages/source/element_kgeobag.rst index 6a408a60..c5cd846a 100644 --- a/Documentation/gh-pages/source/element_kgeobag.rst +++ b/Documentation/gh-pages/source/element_kgeobag.rst @@ -1,6 +1,6 @@ -KGeoBag - geometry definition +KGeoBag - ***************************** .. _KGeoBag: @@ -11,8 +11,8 @@ KGeoBag - geometry definition -Geometry -========= +Geometry section +================= The geometry section of the configuration file is the first piece needed in order to assemble a simulation. At its first and most basic level it is responsible for defining all the different shapes that will be used, and placing them with @@ -352,1514 +352,17 @@ supported shapes are the cylinder surface, describing a simple coil, and the rod For further demonstrations of the possible geometry extensions please see the provided example XML files located at :gh-code:`KGeoBag/Source/XML/Examples`. +KGeoBag shapes +=============== +See the following two chapters for an overview over simple and more advanced shapes: -.. _basic-kgeobag-label: - -Basic Shapes in KGeoBag -========================== - -This section is a description of the basic spaces and surfaces which can be constructed using *KGeoBag*. All of the -following shapes can be displayed by the executables ``MeshViewer`` and ``GeometryViewer`` (see :ref:`visualization-label`). -These executables are built and installed along with *KGeoBag* when it is linked against VTK_. - - -Geometry visualization ------------------------ - -In order to view a geometry you can execute ``GeometryViewer`` from the directory ``$KASPERSYS/install/bin`` with the -path to your geometry file (.xml) and the name of the geometry element you want to display as the arguments: - -.. code-block:: bash - - ./GeometryViewer ../config/TheBag/Examples/ExampleShapes.xml example_rotated_surface - -An example of the geometry view is shown below: - -.. image:: _images/geometryviewer.png - :width: 400pt - -To visualized the mesh of a geometric element execute MeshViewer in ``$KASPERSYS/install/bin`` with the path to your -geometry file (.xml) and the name of the geometry element you want to display: - -.. code-block:: bash - - ./MeshViewer <../config/TheBag/Examples/ExampleShapes.xml> - -There is also an ``AxialMeshViewer`` available, which displays the axial mesh (if defined) in the same way. The -geometric element can be a specific element or several elements collected into a group. To display a single element use -its name, to show a tagged group the argument is written as ``@tag_group``. An example of the mesh viewer being used on -a rod surface is shown below: - -.. image:: _images/meshviewer.png - :width: 400pt - -The ``GeometryViewer`` and ``MeshViewer`` will also produce a VTK poly-data file (.vtp) which can then be open in the -external application Paraview_ for more advanced visualization. - -The parameters specifying the method by which a geometric element is meshed must be given in the geometry file when the -shape is described. If no mesh is desired for some object, the mesh parameters may be ignored and the defaults will be -used. The commands above may also be tried with one of the *Kassiopeia* simulation examples. - -The mesh parameters vary for each object, but essentially describe two properties (for each meshable dimension). These -are the ``mesh_count`` and the ``mesh_power``. If the ``mesh_power`` is set equal to 1.0, then the ``mesh_count`` simply -specifies the number of equally sized segments that a shape will be chopped into, along a particular dimension. If the -``mesh_power`` is greater than 1.0, then the density of segments will increase towards the edges of the shape while -keeping the number of elements the same. The ``mesh_power`` property is useful for tailoring the accuracy of mesh -descriptions for Laplace boundary value problems, where quantities such as charge density may vary considerably near the -sharp edges of an object. Therefore, this parameter is mainly used for electrode meshes. - -The following sections provide examples and brief descriptions of some basic shapes available for use in *KGeoBag*. - -Basic elements --------------- - -The following elements (poly-loop and poly-line) are internal descriptors. They can't be used by themselves outside a -geometry element. This section serves as a brief explanation for the structure of these shapes. - -Poly-loop -~~~~~~~~~~ - -A poly-loop is a closed sequence consisting of several lines and/or arcs that form a polygonal shape. The aequence -starts with ```` and ends with ```` or ````, and multiple ```` or ```` elements can be put in between. An example of a poly-loop element is as follows: - -.. code-block:: xml - - - - - - - - -which creates a line from (0,0) to (0.4,-0.1) followed by an arc to (-0.1,0.4), and then the loop is closed by a line -back to the starting point. Note that poly-loop and poly-line are two-dimensional objects that operate in (x,y) -coordinates. Any line that is created by a ```` command goes from the end-point of the previous line to the -specified coordinate. The directive ```` or ```` connects the first and last points with -the specified segment type. - -The arc elements are described with the boolean parameters ``right`` and ``short``, as shown here: - -.. image:: _images/short_true_false.png - -where ``right="true"`` means that the circle segment will be drawn clockwise, and vice versa. ``short="true"`` means -that the arc will be the shorter one of the two possiblities. - -Poly-line -~~~~~~~~~~ - -This element is desribed using the same procedure as in poly-loop. However, the first and last points are not -necessarily connected. An XML example is below: - -.. code-block:: xml - - - - - - - - - -In this case, the sequence progresses through five (x,y) points but does not connect back to the starting point. Hence, -it does not form a closed loop like the poly-loop element does, and does not need a ```` command. Otherwise, -the parameters for poly-line are the same as for poly-loop. - -Surfaces ------------ - -Flat surfaces -~~~~~~~~~~~~~~ - -Flattened circle surface -""""""""""""""""""""""""""" - -A flattened circle surface is just a surface with circular shape, where (x,y,z) are the coordinates for the center of -the circle and r is the radius: - -.. image:: _images/kgeobag_flattened_circle_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Flattened poly-loop surface -""""""""""""""""""""""""""""" - -A flattened poly loop surface is a surface consisting of several lines, arcs or both, creating a polygon of your desired -shape. The first line and the last line are connected automatically. By using the features of the poly-loop outlined -above, this provides a very flexible method of designing surface elements. - -.. image:: _images/kgeobag_flattened_poly_loop_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - -Rotated Surfaces -~~~~~~~~~~~~~~~~~~ - -All rotated surfaces are constructed from lines, arcs, poly-lines, or poly-loops which are then rotated around the local -x-axis. - -Rotated line segment surface -""""""""""""""""""""""""""""""" - -This type generates the surface of revolution formed by a line that is rotated around the x-axis. - -.. image:: _images/kgeobag_rotated_line_segment_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated arc segment surface -""""""""""""""""""""""""""""" - -This type generates the surface of revolution formed by an arc that is rotated around the x-axis. - -.. image:: _images/kgeobag_rotated_arc_segment_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated poly-line surface -""""""""""""""""""""""""""" - -This type generates the surface of revolution created by rotating a poly-line around the local x-axis. - -.. image:: _images/kgeobag_rotated_poly_line_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - -Rotated circle surface -""""""""""""""""""""""" - -This type generates the surface of revolution created by rotating a circle around the local x-axis. This shape is -essentially or torus, or a section of a torus. - -.. image:: _images/kgeobag_rotated_circle_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated poly loop surface -""""""""""""""""""""""""""" - -This type generates the surface of revolution created by rotating a poly-loop around the local x-axis. - -.. image:: _images/kgeobag_rotated_poly_loop_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Shell Surfaces -~~~~~~~~~~~~~~~~~ - -All shell surfaces are lines, arcs or surfaces that are rotated around the x-axis between a given start angle -(angle_start) and stop angle (angle_stop). - -Shell line segment surface -""""""""""""""""""""""""""" - -This produces an angularly limited portion of a surface of revolution from a line that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_line_segment_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Shell arc segment surface -""""""""""""""""""""""""""" - -This produces an angularly limited portion of a surface of revolution from an arc that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_arc_segment_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Shell poly-line surface -""""""""""""""""""""""""" - -This produces an angularly limited portion of a surface of revolution from a poly-line that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_poly_line_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - -Shell circle surface -""""""""""""""""""""" - -This produces an angularly limited portion of a surface of revolution from a circle that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_circle_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Shell poly-loop surface -""""""""""""""""""""""""" - -This produces an angularly limited portion of a surface of revolution from a poly-loop that is rotated around the local -x-axis. - -.. image:: _images/kgeobag_shell_poly_loop_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Extruded Surfaces -~~~~~~~~~~~~~~~~~~~ - -Extruded surfaces are surfaces that are extruded along the direction of the local z-axis from a minimum z-position -(zmin) to a maximum z-position (zmax). - -Extruded poly-line surface -""""""""""""""""""""""""""" - -This generates a surface by extruding a poly-line. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - -Extruded circle surface -""""""""""""""""""""""""" - -This generates the surfaced produced by extruding a circle (this is the same as a cylinder). - -.. image:: _images/kgeobag_extruded_circle_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Extruded poly-loop surface -""""""""""""""""""""""""""" - -This generates a surface by extruding a poly-loop. - -.. image:: _images/kgeobag_extruded_poly_loop_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Special Surfaces -~~~~~~~~~~~~~~~~~ - -These surfaces are just specific cases of the more general surface types already listed. However, since their use is -extremely common, they have been made available as unique, special types. For many simple simulations, it is possible -to design the geometry entirely using these elements. - -Disk surface -""""""""""""" - -This produces a disk centered on the local z-axis. - -.. image:: _images/kgeobag_disk_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z: z-position in meters -- r: radius in meters -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Annulus surface -""""""""""""""""" -This produces an annulus centered on the z axis. - -.. image:: _images/kgeobag_annulus_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z: z-position in meters -- r1: the first of the radii in meters -- r2: the second radius in meters -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cylinder surface -""""""""""""""""" - -Generates a cylinder centered on the z axis. - -.. image:: _images/kgeobag_cylinder_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z position in meters -- z2: the second z position in meters -- r: radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cone Surface -""""""""""""""" - -Generates a cone centered on the z axis. - -.. image:: _images/kgeobag_cone_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- za: apex z position in meters -- zb: base z position in meters -- rb: base radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cut Cone Surface -""""""""""""""""" - -Produces a truncated cone centered on the local z-axis. - -.. image:: _images/kgeobag_cut_cone_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z coordinates in meters -- r1: the first r coordinates in meters -- z2: the second z coordinate in meters -- r2: the second r coordinate in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Torus Surface -""""""""""""""" - -Generates a torus centered on the local z axis. - -.. image:: _images/kgeobag_torus_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z: z coordinate of the center in meters -- r: r coordinate of the center in meters -- radius: the toroidal radius in meters -- toroidal_mesh_count: toroidal mesh parameter (default is 64) -- axial_mesh_count: axial mesh parameter (default is 64) - -Cut Torus Surface -""""""""""""""""""" - -Produces an angularly limited toroidal section centered on the z axis. - -.. image:: _images/kgeobag_cut_torus_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z coordinate in meters -- r1: the first r coordinate in meters -- z2: the second z coordinate in meters -- r2: the second r coordinate in meters -- radius: the toroidal radius in meters -- right: is the arc on the right side of the directed line connecting point 1 to point 2? -- short: does the arc subtend less than pi radians? -- toroidal_mesh_count: toroidal mesh parameter (default is 64) -- axial_mesh_count: axial mesh parameter (default is 64) - - -Spaces --------- - -Spaces are considered distinct from surfaces as they are (water-tight) volumes. The cannot be open or have holes which -puncture their boundaries. In the *Kassiopeia* interface, spaces are treated very differently than surfaces and have -different features on purposes. - -Extruded Spaces -~~~~~~~~~~~~~~~~ - -Extruded spaces are from in a manner similar to extruded surfaces, the only difference being that they also provide -planar caps to fully enclose a central volume. - -Extruded Circle Space -""""""""""""""""""""""""" - -Generates a volume by extruding a cycle (cynlinder). - -.. image:: _images/kgeobag_extruded_circle_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Extruded Poly-Loop Space -""""""""""""""""""""""""""" - -Generates a volume by extruding a poly-loop. - -.. image:: _images/kgeobag_extruded_poly_loop_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Rotated Spaces -~~~~~~~~~~~~~~~~ - -Rotated Line Segment -""""""""""""""""""""" - -Generates a volume enclosed by a surface of revolution produced from rotating a line segement. - -.. image:: _images/kgeobag_rotated_line_segment_space_model.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated Arc Segment -""""""""""""""""""""" - -Generates a volume enclosed by a surface of revolution produced from rotating an arc segment. - -.. image:: _images/kgeobag_rotated_arc_segment_space_model.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated Poly-Line Space -""""""""""""""""""""""""" - -Generates a volume enclosed by a surface of revolution produced from rotating a poly-line. - -.. image:: _images/kgeobag_rotated_poly_line_space_model.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - -Rotated Circle Space -""""""""""""""""""""" - -Generates a volume by rotating a circle (torus). - -.. image:: _images/kgeobag_rotated_circle_space_model.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - -Rotated Poly-Loop Space -""""""""""""""""""""""""" - -Generates a volume enclosed by a surface of revolution produced from rotating a poly-loop - -.. image:: _images/kgeobag_rotated_poly_loop_space_model.png - :width: 400pt - -- Works with GeometryViewer: No. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - -Special Spaces -~~~~~~~~~~~~~~~~ - -These spaces are just specific cases of the more general space types already listed. They have been made separately -available because of their common use. As with the special surfaces, these elements may be used to design a simple -simulation geometry. - -Cylinder Space -""""""""""""""" - -Produces a cylinder space centered on the local z axis. - -.. image:: _images/kgeobag_cylinder_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - - z1: the first z coordinate in meters - - z2: the second z coordinate in meters - - r: the radius in meters - - longitudinal_mesh_count: longitudinal mesh parameter (default is 1) - - longitudinal_mesh_power: longitudinal meshing power (default is 1.) - - radial_mesh_count: radial mesh parameter (default is 1) - - radial_mesh_power: radial meshing power (default is 1.) - - axial_mesh_count: axial mesh parameter (default is 16) - -Cone Space -""""""""""""" - -Generates a conical space centered on the local z axis. - -.. image:: _images/kgeobag_cone_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- za: apex z position in meters -- zb: base z position in meters -- rb: base radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cut Cone Space -""""""""""""""" - -Produces a cut cone volume (frustrum). - -.. image:: _images/kgeobag_cut_cone_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z coordinate in meters -- r1: the first r coordinate in meters -- z2: the second z coordinate in meters -- r2: the second r coordinate in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -Torus Space -""""""""""""" - -Produces a torus centered on the local z axis. - -.. image:: _images/kgeobag_torus_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z: z coordinate of the center in meters -- r: r coordinate of the center in meters -- radius: the toroidal radius in meters -- toroidal_mesh_count: toroidal mesh parameter (default is 64) -- axial_mesh_count: axial mesh parameter (default is 64) - -Cylinder Tube Space -""""""""""""""""""""" - -Creates a tube, (a hollow cylinder with finite wall thickness). - -.. image:: _images/kgeobag_cylinder_tube_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first z position in meters -- z2: the second z position in meters -- r1: the first radius in meters -- r2: the second radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Cut Cone Tube Space -""""""""""""""""""""" - -Generates a tubular frustrum (a cut cone with central axially symmetric void). - -.. image:: _images/kgeobag_cut_cone_tube_space_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- z1: the first side's z position in meters -- z2: the second side's z position in meters -- r11: one of the side's first radius in meters -- r12: the other side's first radius in meters -- r21: one of the side's second radius in meters -- r22: the other side' second radius in meters -- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) -- longitudinal_mesh_power: longitudinal meshing power (default is 1.) -- radial_mesh_count: radial mesh parameter (default is 1) -- radial_mesh_power: radial meshing power (default is 1.) -- axial_mesh_count: axial mesh parameter (default is 16) - -Box Space -""""""""""""" - -Produces an axis aligned rectangular prism. - -.. image:: _images/kgeobag_box_space_model.png - :width: 400pt - -- Works with MeshViewer: No. -- Works with GeometryViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - -The parameters are: - -- xa: one of the x extrema in meters -- xb: the other x extremum in meters -- x_mesh_count: x mesh count -- x_mesh_power: x mesh power -- ya: one of the y extrema in meters -- yb: the other y extremum in meters -- y_mesh_count: y mesh count -- y_mesh_power: y mesh power -- za: one of the z extrema in meters -- zb: the other z extremum in meters -- z_mesh_count: z mesh count -- z_mesh_power: z mesh power - - -.. _complex-kgeobag-label: - -Complex Shapes in KGeoBag -========================= - -This section describes the more complicated shapes available in *KGeoBag*. Since as of yet, *KGeoBag* lacks the ability -to perform boolean operations on solids (constructive solid geometry), shapes which cannot be represented as an assembly -of basic shapes must be explicitly defined in C++. However, to augment the basic shapes, *KGeoBag* provides some -additional complex shapes that are commonly encountered in experimental structures such as vacuum chambers, etc. - -Some of the examples in this section make use of the the more advanced features of the XML parser, including loops, -conditional statements, and equation evaluation. - -Surfaces ----------- - -Pump Port Surface -~~~~~~~~~~~~~~~~~~ - -The shape creates a tube-like surface with circular or rectangular pump ports (e.g. for vacuum chambers). The -coordinates (x,y,z) are the end points of the ports. The ports can only be created in radial direction. - -.. image:: _images/kgeobag_port_housing_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - -Conic Section Pump Port Surface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This shape is a cut cone surface with circular ports. The ports can be created either orthogonal to the surface or -parallel to the cone axis (paraxial). The coordinates (x,y,z) are the end points of the port. - -.. image:: _images/kgeobag_conic_section_port_housing_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - -Beam Surface -~~~~~~~~~~~~~~ - -A beam creates a pipe which connects two polygons at each end. The polygons must have the same number of vertices but -may lie in planes which are not parallel to each other. For the description of the parameters involved see the images -below. - -.. image:: _images/beam_description.png - :width: 250pt - -In the following example, the variable ``[poly]`` dictates the the number of vertexes in each polygon at the ends of the -beam. - -.. image:: _images/kgeobag_beam_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - -Multi-cut surfaces -""""""""""""""""""" - -The beam shape can also be used to create more complex objects, such as a cut cone with two more cuts at both ends. - -.. image:: _images/kgeobag_multicut_surface_model.png - :width: 400pt - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - -Rod Surface -~~~~~~~~~~~~~ - -The rod element can be used to create a rod like structure along a series of linear segments in three dimensional space. -The rod has a circular cross section which is approximated by a polygon (governed by the ``axial_mesh_count`` -parameter). This shape is defined by a radius (thickness of the rod) and a piecewise linear path specified by a by a -list of in-order vertexes. - -.. image:: _images/kgeobag_rod_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -The following XML example creates a helix shaped rod surface, as follows: - -.. code-block:: xml - - - - - - - - - - - - - -Extruded Surfaces with holes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -With this element it is possible to create an extruded surface (from a poly-loop like curve) with arbitrary holes in it. -The commands ```` and ```` define whether the extruded path will produce an outer or an inner -surface. Therefore, they define if there will be a hole in the surface and its shape. - -.. image:: _images/kgeobag_extruded_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - -Rotated Surface -~~~~~~~~~~~~~~~~~~~~ - -This shape is very similar to rotated poly-line surface in :ref:`basic-kgeobag-label` but with other variables. The -coordinates in use in this shape are cylindrical. (z,r) - -.. image:: _images/kgeobag_rotated_surface_model.png - :width: 400pt - -- Works with MeshViewer: Yes. -- Works with GeometryViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - -Spaces --------- - -These elements generate volume (filled) objects. The for the following geometries is not supported at the moment. For -the definition of the variables see the corresponding surfaces above. - -Pump Port Space -~~~~~~~~~~~~~~~~~~ - -For visualization, see the above pump port surface. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - -Conic Section Pump Port Space -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For visualization, see the above conic section pump port surface. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - -Beam Space -~~~~~~~~~~~~~ - -For visualization, see the beam surface above. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - - - -Rod Space -~~~~~~~~~~ - -For visualization, see the above rod surface. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - -Extruded Space -~~~~~~~~~~~~~~~~~~ - -For visualization see the above extruded space. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - -Rotated Space -~~~~~~~~~~~~~~~~ - -For visualization see the above rotated surface. - -- Works with GeometryViewer: No. -- Works with MeshViewer: No. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - - -Shapes from imported files ------------------------------ - -As an alternative to defining geometries via the XML file format, one may also use geometric objects from external -files. The only available file format is STL, which is supported by the majority of current 3D design software. The -STL file contains a set of triangles, which are treated as a fully meshed geometry in *KGeoBag*. As such, the geometry -is usable with *KEMField* (for electric field calculation) and *Kassiopeia* (for particle navigation.) - - -STL File Surface -~~~~~~~~~~~~~~~~~~~ - -.. image:: _images/kgeobag_teapot_mesh.png - :width: 400pt - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - - - - - - - - -Note that because the geometry is defined by an external file, the possible modifications in the *KGeoBag* framework -are limited. Besides the translations/rotations that can be applied to any object, one may also scale the external -geometry or increase its number of mesh elements. If the triangles in the file are sufficienctly ordered, then one -can use the ``selector`` attribute to specify indices of the triangles to be used in *KGeoBag*. In the case of the -``Utah_teapot.stl`` example file, this allows to split the lid from the pot's body. - -STL File Space -~~~~~~~~~~~~~~~~~~ - -For visualization see the above STL file surface. - -- Works with GeometryViewer: Yes. -- Works with MeshViewer: Yes. - -An XML example is as follows: - -.. code-block:: xml - - - - - - +.. toctree:: + :maxdepth: 1 + + kgeobag_simple_shapes + kgeobag_complex_shapes .. _TFormula: http://root.cern.ch/root/htmldoc/TFormula.html diff --git a/Documentation/gh-pages/source/index.rst b/Documentation/gh-pages/source/index.rst index c713163f..e78bc2a1 100644 --- a/Documentation/gh-pages/source/index.rst +++ b/Documentation/gh-pages/source/index.rst @@ -68,9 +68,9 @@ Welcome to Kassiopeia's documentation! Running Kassiopeia Example configurations Configuring your own simulation - KGeoBag - geometry definition - KEMField - field definition - Kassiopeia element + KGeoBag - + Field definition - + Particle tracking - .. toctree:: @@ -86,7 +86,7 @@ Welcome to Kassiopeia's documentation! This simulation package by `the KATRIN collaboration`_ allows to run highly customizable particle tracking simulations -along with calculations of electric and magnetic fields. +along with calculations of electric and magnetic fields. *Kassiopeia* is supported and intended to run on systems running either Linux or MacOS X. diff --git a/Documentation/gh-pages/source/introduction.rst b/Documentation/gh-pages/source/introduction.rst index f4abf06d..a414f102 100644 --- a/Documentation/gh-pages/source/introduction.rst +++ b/Documentation/gh-pages/source/introduction.rst @@ -46,16 +46,4 @@ certain specific features in their own novel applications. Code contributions th can be submitted through GitHub and are always welcome. - - - -Supported operating systems and hardware requirements -===================================================== - -*Kassiopeia* is supported and intended to run on systems running either Linux or MacOS X. Currently, it has been -compiled and tested to run on fresh installations of the Linux distributions Fedora 31 and Ubuntu 20.04 LTS. It is also -expected to compile and run on other Linux distributions, however this has not been tested, and the steps needed to -compile *Kassiopeia* may deviate from what is outlined here. - - .. _KATRIN: https://www.katrin.kit.edu \ No newline at end of file diff --git a/Documentation/gh-pages/source/kgeobag_complex_shapes.rst b/Documentation/gh-pages/source/kgeobag_complex_shapes.rst new file mode 100644 index 00000000..225d7f7e --- /dev/null +++ b/Documentation/gh-pages/source/kgeobag_complex_shapes.rst @@ -0,0 +1,474 @@ + +.. _complex-kgeobag-label: + +Complex Shapes in KGeoBag +========================= + +This section describes the more complicated shapes available in *KGeoBag*. Since as of yet, *KGeoBag* lacks the ability +to perform boolean operations on solids (constructive solid geometry), shapes which cannot be represented as an assembly +of basic shapes must be explicitly defined in C++. However, to augment the basic shapes, *KGeoBag* provides some +additional complex shapes that are commonly encountered in experimental structures such as vacuum chambers, etc. + +Some of the examples in this section make use of the the more advanced features of the XML parser, including loops, +conditional statements, and equation evaluation. + +Surfaces +---------- + +Pump Port Surface +~~~~~~~~~~~~~~~~~~ + +The shape creates a tube-like surface with circular or rectangular pump ports (e.g. for vacuum chambers). The +coordinates (x,y,z) are the end points of the ports. The ports can only be created in radial direction. + +.. image:: _images/kgeobag_port_housing_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + +Conic Section Pump Port Surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This shape is a cut cone surface with circular ports. The ports can be created either orthogonal to the surface or +parallel to the cone axis (paraxial). The coordinates (x,y,z) are the end points of the port. + +.. image:: _images/kgeobag_conic_section_port_housing_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + +Beam Surface +~~~~~~~~~~~~~~ + +A beam creates a pipe which connects two polygons at each end. The polygons must have the same number of vertices but +may lie in planes which are not parallel to each other. For the description of the parameters involved see the images +below. + +.. image:: _images/beam_description.png + :width: 250pt + +In the following example, the variable ``[poly]`` dictates the the number of vertexes in each polygon at the ends of the +beam. + +.. image:: _images/kgeobag_beam_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + +Multi-cut surfaces +""""""""""""""""""" + +The beam shape can also be used to create more complex objects, such as a cut cone with two more cuts at both ends. + +.. image:: _images/kgeobag_multicut_surface_model.png + :width: 400pt + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + +Rod Surface +~~~~~~~~~~~~~ + +The rod element can be used to create a rod like structure along a series of linear segments in three dimensional space. +The rod has a circular cross section which is approximated by a polygon (governed by the ``axial_mesh_count`` +parameter). This shape is defined by a radius (thickness of the rod) and a piecewise linear path specified by a by a +list of in-order vertexes. + +.. image:: _images/kgeobag_rod_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +The following XML example creates a helix shaped rod surface, as follows: + +.. code-block:: xml + + + + + + + + + + + + + +Extruded Surfaces with holes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With this element it is possible to create an extruded surface (from a poly-loop like curve) with arbitrary holes in it. +The commands ```` and ```` define whether the extruded path will produce an outer or an inner +surface. Therefore, they define if there will be a hole in the surface and its shape. + +.. image:: _images/kgeobag_extruded_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + +Rotated Surface +~~~~~~~~~~~~~~~~~~~~ + +This shape is very similar to rotated poly-line surface in :ref:`basic-kgeobag-label` but with other variables. The +coordinates in use in this shape are cylindrical. (z,r) + +.. image:: _images/kgeobag_rotated_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + +Spaces +-------- + +These elements generate volume (filled) objects. The for the following geometries is not supported at the moment. For +the definition of the variables see the corresponding surfaces above. + +Pump Port Space +~~~~~~~~~~~~~~~~~~ + +For visualization, see the above pump port surface. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + +Conic Section Pump Port Space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For visualization, see the above conic section pump port surface. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + +Beam Space +~~~~~~~~~~~~~ + +For visualization, see the beam surface above. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + + +Rod Space +~~~~~~~~~~ + +For visualization, see the above rod surface. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + +Extruded Space +~~~~~~~~~~~~~~~~~~ + +For visualization see the above extruded space. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + +Rotated Space +~~~~~~~~~~~~~~~~ + +For visualization see the above rotated surface. + +- Works with GeometryViewer: No. +- Works with MeshViewer: No. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + +Shapes from imported files +----------------------------- + +As an alternative to defining geometries via the XML file format, one may also use geometric objects from external +files. The only available file format is STL, which is supported by the majority of current 3D design software. The +STL file contains a set of triangles, which are treated as a fully meshed geometry in *KGeoBag*. As such, the geometry +is usable with *KEMField* (for electric field calculation) and *Kassiopeia* (for particle navigation.) + + +STL File Surface +~~~~~~~~~~~~~~~~~~~ + +.. image:: _images/kgeobag_teapot_mesh.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + +Note that because the geometry is defined by an external file, the possible modifications in the *KGeoBag* framework +are limited. Besides the translations/rotations that can be applied to any object, one may also scale the external +geometry or increase its number of mesh elements. If the triangles in the file are sufficienctly ordered, then one +can use the ``selector`` attribute to specify indices of the triangles to be used in *KGeoBag*. In the case of the +``Utah_teapot.stl`` example file, this allows to split the lid from the pot's body. + +STL File Space +~~~~~~~~~~~~~~~~~~ + +For visualization see the above STL file surface. + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + +.. _TFormula: http://root.cern.ch/root/htmldoc/TFormula.html +.. _TMath: http://root.cern.ch/root/htmldoc/TMath.html +.. _PDG: http://pdg.lbl.gov/mc_particle_id_contents.html +.. _Paraview: http://www.paraview.org/ +.. _ROOT: https://root.cern.ch/ +.. _VTK: http://www.vtk.org/ +.. _MKS: https://scienceworld.wolfram.com/physics/MKS.html +.. _XML: https://www.w3.org/TR/xml11/ +.. _Xpath: https://www.w3.org/TR/xpath-10/ +.. _TinyExpr: https://github.com/codeplea/tinyexpr/ +.. _Log4CXX: https://logging.apache.org/log4cxx/ + +.. rubric:: Footnotes + +[1] Daniel Lawrence Furse. Techniques for direct neutrino mass measurement utilizing tritium [beta]-decay. PhD thesis, Massachusetts Institute of Technology, 2015. + +[2] Thomas Corona. Methodology and application of high performance electrostatic field simulation in the KATRIN experiment. PhD thesis, University of North Carolina, Chapel Hill, 2014. + +[3] John P. Barrett. A Spatially Resolved Study of the KATRIN Main Spectrometer Using a Novel Fast Multipole Method. PhD thesis, Massachusetts Institute of Technology, 2016. diff --git a/Documentation/gh-pages/source/kgeobag_simple_shapes.rst b/Documentation/gh-pages/source/kgeobag_simple_shapes.rst new file mode 100644 index 00000000..529fe6ef --- /dev/null +++ b/Documentation/gh-pages/source/kgeobag_simple_shapes.rst @@ -0,0 +1,1074 @@ + +.. _basic-kgeobag-label: + +Basic Shapes in KGeoBag +========================== + +This section is a description of the basic spaces and surfaces which can be constructed using *KGeoBag*. All of the +following shapes can be displayed by the executables ``MeshViewer`` and ``GeometryViewer`` (see :ref:`visualization-label`). +These executables are built and installed along with *KGeoBag* when it is linked against VTK_. + + +Geometry visualization +----------------------- + +In order to view a geometry you can execute ``GeometryViewer`` from the directory ``$KASPERSYS/install/bin`` with the +path to your geometry file (.xml) and the name of the geometry element you want to display as the arguments: + +.. code-block:: bash + + ./GeometryViewer ../config/TheBag/Examples/ExampleShapes.xml example_rotated_surface + +An example of the geometry view is shown below: + +.. image:: _images/geometryviewer.png + :width: 400pt + +To visualized the mesh of a geometric element execute MeshViewer in ``$KASPERSYS/install/bin`` with the path to your +geometry file (.xml) and the name of the geometry element you want to display: + +.. code-block:: bash + + ./MeshViewer <../config/TheBag/Examples/ExampleShapes.xml> + +There is also an ``AxialMeshViewer`` available, which displays the axial mesh (if defined) in the same way. The +geometric element can be a specific element or several elements collected into a group. To display a single element use +its name, to show a tagged group the argument is written as ``@tag_group``. An example of the mesh viewer being used on +a rod surface is shown below: + +.. image:: _images/meshviewer.png + :width: 400pt + +The ``GeometryViewer`` and ``MeshViewer`` will also produce a VTK poly-data file (.vtp) which can then be open in the +external application Paraview_ for more advanced visualization. + +The parameters specifying the method by which a geometric element is meshed must be given in the geometry file when the +shape is described. If no mesh is desired for some object, the mesh parameters may be ignored and the defaults will be +used. The commands above may also be tried with one of the *Kassiopeia* simulation examples. + +The mesh parameters vary for each object, but essentially describe two properties (for each meshable dimension). These +are the ``mesh_count`` and the ``mesh_power``. If the ``mesh_power`` is set equal to 1.0, then the ``mesh_count`` simply +specifies the number of equally sized segments that a shape will be chopped into, along a particular dimension. If the +``mesh_power`` is greater than 1.0, then the density of segments will increase towards the edges of the shape while +keeping the number of elements the same. The ``mesh_power`` property is useful for tailoring the accuracy of mesh +descriptions for Laplace boundary value problems, where quantities such as charge density may vary considerably near the +sharp edges of an object. Therefore, this parameter is mainly used for electrode meshes. + +The following sections provide examples and brief descriptions of some basic shapes available for use in *KGeoBag*. + +Basic elements +-------------- + +The following elements (poly-loop and poly-line) are internal descriptors. They can't be used by themselves outside a +geometry element. This section serves as a brief explanation for the structure of these shapes. + +Poly-loop +~~~~~~~~~~ + +A poly-loop is a closed sequence consisting of several lines and/or arcs that form a polygonal shape. The aequence +starts with ```` and ends with ```` or ````, and multiple ```` or ```` elements can be put in between. An example of a poly-loop element is as follows: + +.. code-block:: xml + + + + + + + + +which creates a line from (0,0) to (0.4,-0.1) followed by an arc to (-0.1,0.4), and then the loop is closed by a line +back to the starting point. Note that poly-loop and poly-line are two-dimensional objects that operate in (x,y) +coordinates. Any line that is created by a ```` command goes from the end-point of the previous line to the +specified coordinate. The directive ```` or ```` connects the first and last points with +the specified segment type. + +The arc elements are described with the boolean parameters ``right`` and ``short``, as shown here: + +.. image:: _images/short_true_false.png + +where ``right="true"`` means that the circle segment will be drawn clockwise, and vice versa. ``short="true"`` means +that the arc will be the shorter one of the two possiblities. + +Poly-line +~~~~~~~~~~ + +This element is desribed using the same procedure as in poly-loop. However, the first and last points are not +necessarily connected. An XML example is below: + +.. code-block:: xml + + + + + + + + + +In this case, the sequence progresses through five (x,y) points but does not connect back to the starting point. Hence, +it does not form a closed loop like the poly-loop element does, and does not need a ```` command. Otherwise, +the parameters for poly-line are the same as for poly-loop. + +Surfaces +----------- + +Flat surfaces +~~~~~~~~~~~~~~ + +Flattened circle surface +""""""""""""""""""""""""""" + +A flattened circle surface is just a surface with circular shape, where (x,y,z) are the coordinates for the center of +the circle and r is the radius: + +.. image:: _images/kgeobag_flattened_circle_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Flattened poly-loop surface +""""""""""""""""""""""""""""" + +A flattened poly loop surface is a surface consisting of several lines, arcs or both, creating a polygon of your desired +shape. The first line and the last line are connected automatically. By using the features of the poly-loop outlined +above, this provides a very flexible method of designing surface elements. + +.. image:: _images/kgeobag_flattened_poly_loop_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + +Rotated Surfaces +~~~~~~~~~~~~~~~~~~ + +All rotated surfaces are constructed from lines, arcs, poly-lines, or poly-loops which are then rotated around the local +x-axis. + +Rotated line segment surface +""""""""""""""""""""""""""""""" + +This type generates the surface of revolution formed by a line that is rotated around the x-axis. + +.. image:: _images/kgeobag_rotated_line_segment_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated arc segment surface +""""""""""""""""""""""""""""" + +This type generates the surface of revolution formed by an arc that is rotated around the x-axis. + +.. image:: _images/kgeobag_rotated_arc_segment_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated poly-line surface +""""""""""""""""""""""""""" + +This type generates the surface of revolution created by rotating a poly-line around the local x-axis. + +.. image:: _images/kgeobag_rotated_poly_line_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + +Rotated circle surface +""""""""""""""""""""""" + +This type generates the surface of revolution created by rotating a circle around the local x-axis. This shape is +essentially or torus, or a section of a torus. + +.. image:: _images/kgeobag_rotated_circle_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated poly loop surface +""""""""""""""""""""""""""" + +This type generates the surface of revolution created by rotating a poly-loop around the local x-axis. + +.. image:: _images/kgeobag_rotated_poly_loop_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Shell Surfaces +~~~~~~~~~~~~~~~~~ + +All shell surfaces are lines, arcs or surfaces that are rotated around the x-axis between a given start angle +(angle_start) and stop angle (angle_stop). + +Shell line segment surface +""""""""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from a line that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_line_segment_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Shell arc segment surface +""""""""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from an arc that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_arc_segment_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Shell poly-line surface +""""""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from a poly-line that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_poly_line_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + +Shell circle surface +""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from a circle that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_circle_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Shell poly-loop surface +""""""""""""""""""""""""" + +This produces an angularly limited portion of a surface of revolution from a poly-loop that is rotated around the local +x-axis. + +.. image:: _images/kgeobag_shell_poly_loop_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Extruded Surfaces +~~~~~~~~~~~~~~~~~~~ + +Extruded surfaces are surfaces that are extruded along the direction of the local z-axis from a minimum z-position +(zmin) to a maximum z-position (zmax). + +Extruded poly-line surface +""""""""""""""""""""""""""" + +This generates a surface by extruding a poly-line. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + +Extruded circle surface +""""""""""""""""""""""""" + +This generates the surfaced produced by extruding a circle (this is the same as a cylinder). + +.. image:: _images/kgeobag_extruded_circle_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Extruded poly-loop surface +""""""""""""""""""""""""""" + +This generates a surface by extruding a poly-loop. + +.. image:: _images/kgeobag_extruded_poly_loop_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Special Surfaces +~~~~~~~~~~~~~~~~~ + +These surfaces are just specific cases of the more general surface types already listed. However, since their use is +extremely common, they have been made available as unique, special types. For many simple simulations, it is possible +to design the geometry entirely using these elements. + +Disk surface +""""""""""""" + +This produces a disk centered on the local z-axis. + +.. image:: _images/kgeobag_disk_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z: z-position in meters +- r: radius in meters +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Annulus surface +""""""""""""""""" +This produces an annulus centered on the z axis. + +.. image:: _images/kgeobag_annulus_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z: z-position in meters +- r1: the first of the radii in meters +- r2: the second radius in meters +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cylinder surface +""""""""""""""""" + +Generates a cylinder centered on the z axis. + +.. image:: _images/kgeobag_cylinder_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z position in meters +- z2: the second z position in meters +- r: radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cone Surface +""""""""""""""" + +Generates a cone centered on the z axis. + +.. image:: _images/kgeobag_cone_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- za: apex z position in meters +- zb: base z position in meters +- rb: base radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cut Cone Surface +""""""""""""""""" + +Produces a truncated cone centered on the local z-axis. + +.. image:: _images/kgeobag_cut_cone_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z coordinates in meters +- r1: the first r coordinates in meters +- z2: the second z coordinate in meters +- r2: the second r coordinate in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Torus Surface +""""""""""""""" + +Generates a torus centered on the local z axis. + +.. image:: _images/kgeobag_torus_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z: z coordinate of the center in meters +- r: r coordinate of the center in meters +- radius: the toroidal radius in meters +- toroidal_mesh_count: toroidal mesh parameter (default is 64) +- axial_mesh_count: axial mesh parameter (default is 64) + +Cut Torus Surface +""""""""""""""""""" + +Produces an angularly limited toroidal section centered on the z axis. + +.. image:: _images/kgeobag_cut_torus_surface_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z coordinate in meters +- r1: the first r coordinate in meters +- z2: the second z coordinate in meters +- r2: the second r coordinate in meters +- radius: the toroidal radius in meters +- right: is the arc on the right side of the directed line connecting point 1 to point 2? +- short: does the arc subtend less than pi radians? +- toroidal_mesh_count: toroidal mesh parameter (default is 64) +- axial_mesh_count: axial mesh parameter (default is 64) + + +Spaces +-------- + +Spaces are considered distinct from surfaces as they are (water-tight) volumes. The cannot be open or have holes which +puncture their boundaries. In the *Kassiopeia* interface, spaces are treated very differently than surfaces and have +different features on purposes. + +Extruded Spaces +~~~~~~~~~~~~~~~~ + +Extruded spaces are from in a manner similar to extruded surfaces, the only difference being that they also provide +planar caps to fully enclose a central volume. + +Extruded Circle Space +""""""""""""""""""""""""" + +Generates a volume by extruding a cycle (cynlinder). + +.. image:: _images/kgeobag_extruded_circle_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Extruded Poly-Loop Space +""""""""""""""""""""""""""" + +Generates a volume by extruding a poly-loop. + +.. image:: _images/kgeobag_extruded_poly_loop_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Rotated Spaces +~~~~~~~~~~~~~~~~ + +Rotated Line Segment +""""""""""""""""""""" + +Generates a volume enclosed by a surface of revolution produced from rotating a line segement. + +.. image:: _images/kgeobag_rotated_line_segment_space_model.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated Arc Segment +""""""""""""""""""""" + +Generates a volume enclosed by a surface of revolution produced from rotating an arc segment. + +.. image:: _images/kgeobag_rotated_arc_segment_space_model.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated Poly-Line Space +""""""""""""""""""""""""" + +Generates a volume enclosed by a surface of revolution produced from rotating a poly-line. + +.. image:: _images/kgeobag_rotated_poly_line_space_model.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + +Rotated Circle Space +""""""""""""""""""""" + +Generates a volume by rotating a circle (torus). + +.. image:: _images/kgeobag_rotated_circle_space_model.png + :width: 400pt + +- Works with GeometryViewer: Yes. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + +Rotated Poly-Loop Space +""""""""""""""""""""""""" + +Generates a volume enclosed by a surface of revolution produced from rotating a poly-loop + +.. image:: _images/kgeobag_rotated_poly_loop_space_model.png + :width: 400pt + +- Works with GeometryViewer: No. +- Works with MeshViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + + + + + + + + + + + + + +Special Spaces +~~~~~~~~~~~~~~~~ + +These spaces are just specific cases of the more general space types already listed. They have been made separately +available because of their common use. As with the special surfaces, these elements may be used to design a simple +simulation geometry. + +Cylinder Space +""""""""""""""" + +Produces a cylinder space centered on the local z axis. + +.. image:: _images/kgeobag_cylinder_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + - z1: the first z coordinate in meters + - z2: the second z coordinate in meters + - r: the radius in meters + - longitudinal_mesh_count: longitudinal mesh parameter (default is 1) + - longitudinal_mesh_power: longitudinal meshing power (default is 1.) + - radial_mesh_count: radial mesh parameter (default is 1) + - radial_mesh_power: radial meshing power (default is 1.) + - axial_mesh_count: axial mesh parameter (default is 16) + +Cone Space +""""""""""""" + +Generates a conical space centered on the local z axis. + +.. image:: _images/kgeobag_cone_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- za: apex z position in meters +- zb: base z position in meters +- rb: base radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cut Cone Space +""""""""""""""" + +Produces a cut cone volume (frustrum). + +.. image:: _images/kgeobag_cut_cone_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z coordinate in meters +- r1: the first r coordinate in meters +- z2: the second z coordinate in meters +- r2: the second r coordinate in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +Torus Space +""""""""""""" + +Produces a torus centered on the local z axis. + +.. image:: _images/kgeobag_torus_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z: z coordinate of the center in meters +- r: r coordinate of the center in meters +- radius: the toroidal radius in meters +- toroidal_mesh_count: toroidal mesh parameter (default is 64) +- axial_mesh_count: axial mesh parameter (default is 64) + +Cylinder Tube Space +""""""""""""""""""""" + +Creates a tube, (a hollow cylinder with finite wall thickness). + +.. image:: _images/kgeobag_cylinder_tube_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first z position in meters +- z2: the second z position in meters +- r1: the first radius in meters +- r2: the second radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Cut Cone Tube Space +""""""""""""""""""""" + +Generates a tubular frustrum (a cut cone with central axially symmetric void). + +.. image:: _images/kgeobag_cut_cone_tube_space_model.png + :width: 400pt + +- Works with MeshViewer: Yes. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- z1: the first side's z position in meters +- z2: the second side's z position in meters +- r11: one of the side's first radius in meters +- r12: the other side's first radius in meters +- r21: one of the side's second radius in meters +- r22: the other side' second radius in meters +- longitudinal_mesh_count: longitudinal mesh parameter (default is 1) +- longitudinal_mesh_power: longitudinal meshing power (default is 1.) +- radial_mesh_count: radial mesh parameter (default is 1) +- radial_mesh_power: radial meshing power (default is 1.) +- axial_mesh_count: axial mesh parameter (default is 16) + +Box Space +""""""""""""" + +Produces an axis aligned rectangular prism. + +.. image:: _images/kgeobag_box_space_model.png + :width: 400pt + +- Works with MeshViewer: No. +- Works with GeometryViewer: Yes. + +An XML example is as follows: + +.. code-block:: xml + + + +The parameters are: + +- xa: one of the x extrema in meters +- xb: the other x extremum in meters +- x_mesh_count: x mesh count +- x_mesh_power: x mesh power +- ya: one of the y extrema in meters +- yb: the other y extremum in meters +- y_mesh_count: y mesh count +- y_mesh_power: y mesh power +- za: one of the z extrema in meters +- zb: the other z extremum in meters +- z_mesh_count: z mesh count +- z_mesh_power: z mesh power + + +.. _TFormula: http://root.cern.ch/root/htmldoc/TFormula.html +.. _TMath: http://root.cern.ch/root/htmldoc/TMath.html +.. _PDG: http://pdg.lbl.gov/mc_particle_id_contents.html +.. _Paraview: http://www.paraview.org/ +.. _ROOT: https://root.cern.ch/ +.. _VTK: http://www.vtk.org/ +.. _MKS: https://scienceworld.wolfram.com/physics/MKS.html +.. _XML: https://www.w3.org/TR/xml11/ +.. _Xpath: https://www.w3.org/TR/xpath-10/ +.. _TinyExpr: https://github.com/codeplea/tinyexpr/ +.. _Log4CXX: https://logging.apache.org/log4cxx/ + +.. rubric:: Footnotes + +[1] Daniel Lawrence Furse. Techniques for direct neutrino mass measurement utilizing tritium [beta]-decay. PhD thesis, Massachusetts Institute of Technology, 2015. + +[2] Thomas Corona. Methodology and application of high performance electrostatic field simulation in the KATRIN experiment. PhD thesis, University of North Carolina, Chapel Hill, 2014. + +[3] John P. Barrett. A Spatially Resolved Study of the KATRIN Main Spectrometer Using a Novel Fast Multipole Method. PhD thesis, Massachusetts Institute of Technology, 2016.