Making your own XML
To see the full documentation for this markup, look to http://clasweb.jlab.org/12gev/software/docs/HDDS-1_0.txt. There should also be a HDDS-1_0.xsd inside your Sim12 directory, and I highly recommend you read through it as it gives a much deeper understanding of the HDDS XML definitions. This guide is meant to just get you started with your own xml. You should back up your clas12.xml and begin by taking things out of it to simplify the geometry. You will find that simulations run MUCH faster without the excess geometry.
The xml files defining the geometry you want to smash particles into is fairly straightforward. I am no expert on the matter but xml is pretty intuitive. The first example is a simple xml file I created/hacked from clas12.xml in order to use just the target and 2 SVTs. (Or two layers on 1 svt...) It is the full file seperated into chunks with dashed lines. The dashed lines should NOT be in your xml file. Each section seperated by dashed lines is described in it's own area below.
Example 1 - Full file, just SVT 1 & 2
Below is the full file needed to define this geometry; just SVT1, SVT2, and the target. Read through it first, as XML is pretty intuitive if you have programmed or coded before. Each section is broken down afterwards. Again, note that the dashes are NOT apart of the orginial XML file, and that XML comments follow the form .
-----------------------------------------------------------------------------------------
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE HDDS [
<!ENTITY Regions_s SYSTEM "Regions_clas12.xml">
<!ENTITY Material_s SYSTEM "Material_HDDS.xml">
<!-- DETECTORS -->
<!ENTITY INNER_spec_s SYSTEM "inner_detector_HDDS.xml">
]>
-----------------------------------------------------------------------------------------
<HDDS specification="v1.0" xmlns="http://www.gluex.org/hdds"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.gluex.org/hdds HDDS-1_0.xsd">
<!-- Include materials -->
&Material_s;
<!-- Include magnetic fields -->
&Regions_s;
<section name = "Kyle's Geometry"
version = ".01"
date = "2007-10-25"
author = "Kyle Snavely"
top_volume = "SITE"
specification = "v1.0"
>
------------------------------------------------------------------------------------------
<box name="SITE" X_Y_Z="3000. 3000. 3000." material="Vacuum" comment="Master Volume" >
<!-- <apply region="ihep-solenoid"/>-->
</box>
<!-- Inner Detector -->
&INNER_spec_s;
<composition name="centralCLAS" envelope="CENT">
<posXYZ volume="TARG" X_Y_Z="0. 0. 0." />
<posXYZ volume="SVT1" X_Y_Z="0. 0. 0." />
<posXYZ volume="SVT2" X_Y_Z="0. 0. 0." />
</composition>
<!--Everything-->
<composition name="everything" envelope="SITE">
<posXYZ volume="centralCLAS" X_Y_Z="0. 0. 0." />
</composition>
</section>
</HDDS>
------------------------------------------------------------------------------------------
XML Decleration and DOCTYPE
The markup below contains the basic information the computer needs to read our XML. The line <?xml version="1.0" encoding="UTF-8"?> is the XML decleration. It tells whatever is using the XML which...well which version and character encoding our document uses. It's nothing to be concerned about but one should include it in his or her documents.
More importantly is the line <!DOCTYPE HDDS [.........]> The word HDDS signifies that our document is coded with tags from the HDDS document type definition; ie it is an HDDS document. The lines <!ENTITY Regions_s SYSTEM "Regions_clas12.xml"> and <!ENTITY Material_s SYSTEM "Material_HDDS.xml"> Basically tell one that any information regarding 'Regions_s' is found in 'Regions_clas12.xml'; the same for Material_s. Finally, the same is done for INNER_spec_s. This is the xml file containing the definitions for the inner detector; the SVTs, target and coil/cryostat.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE HDDS [ <!ENTITY Regions_s SYSTEM "Regions_clas12.xml"> <!ENTITY Material_s SYSTEM "Material_HDDS.xml"> <!-- DETECTORS --> <!ENTITY INNER_spec_s SYSTEM "inner_detector_HDDS.xml"> ]>
HDDS Specification, includes, and sections
<HDDS specification="v1.0" xmlns="http://www.gluex.org/hdds"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.gluex.org/hdds HDDS-1_0.xsd">
<!-- Include materials -->
&Material_s;
<!-- Include magnetic fields -->
&Regions_s;
<section name = "Kyle's Geometry"
version = ".01"
date = "2007-10-25"
author = "Kyle Snavely"
top_volume = "SITE"
specification = "v1.0"
>
The lines in the <HDDS specification.....> are what say, 'yes, this is an HDDS document and these are the keywords to look for.' HDDS-1_0.xsd is in your Sim12 directory and contains a huge amount of information on the geometry and xml markup. After this guide, begin poking around there. Next are the includes; &Material_s basically tells the program to look inside the entity Material_s (which we defined as Regions_clas12.xml, in your Sim12 directory) for anything it may not recognize. (Like for instance, references to things like element names) Regions_s is used to define things like electromagnetic fields. Finally, the section name contains information on the geometry you are creating. Of note is top_volume, which is the container in which everything else is located.
Geometry and end tags
<box name="SITE" X_Y_Z="3000. 3000. 3000." material="Vacuum" comment="Master Volume" >
</box>
<!-- Inner Detector -->
&INNER_spec_s;
<composition name="centralCLAS" envelope="CENT">
<posXYZ volume="TARG" X_Y_Z="0. 0. 0." />
<posXYZ volume="SVT1" X_Y_Z="0. 0. 0." />
<posXYZ volume="SVT2" X_Y_Z="0. 0. 0." />
</composition>
<!--Everything-->
<composition name="everything" envelope="SITE">
<posXYZ volume="centralCLAS" X_Y_Z="0. 0. 0." />
</composition>
</section>
</HDDS>
The tag <box...></box> defines an object (in this case a box or rectangular prism) of size X_Y_Z="width depth height". The attribute 'material' accepts any valid material from Material_s, in this case, "Vacuum". The comment is a human-readable description. Next we see an include for INNER_spec_S, which contains information on the inner detector. Next, <composition name="centralCLAS"...> basically says 'Take everything I list below, at these positions, and lets just call them 'whatever envelope equals' IE, now TARG, SVT1, and SVT2 are children of CENT. NOTE: X_Y_Z is used in this case to specify POSITION, not volume. This changes based on what you are doing. The same is redundantly done for the whole geometry, enveloping everything under the name 'SITE'. And your done!
Going a little further, Editing the Target
Although I would leave Materials_HDDS.xml and Regions_clas12.xml alone at first, if you take a look inside inner_detector_HDDS.xml you will notice entries like this:
<tubs name="TARG" Rio_Z=" 0.00 0.35 5.00" material="LiqHydrogen" comment="Hydrogen Target" />
This, if you couldn't guess, is the target, what we're blasting with 250 PeV of insanity! Or whatever we're using. You've read the Sim12_Batch_Guide haven't you? The most important thing here is the material. In the default inner detector description the target is Liquid Hydrogen. You can change it to whatever you want, and test your simulation. I do not know of a way to edit this at run time. You can change it to anything in Materials_HDDS.xml which has a full definition, like:
<element name="Tin" symbol="Sn" z="50" a="118.69"> <real name="density" value="7.31" unit="g/cm^3" /> <real name="radlen" value="8.82" unit="g/cm^2" /> <real name="collen" value="100.2" unit="g/cm^2" /> <real name="abslen" value="163" unit="g/cm^2" /> <real name="dedx" value="1.264" unit="MeV/g/cm^2" /> </element>
but NOT
<element name="Iodine" symbol="I" z="53" a="126.9046"> <real name="density" value="7.30" unit="g/cm^3" /> </element>
Iodine is not well defined enough so start shooting at, but if you wanted to fire at tin, simply substitute name="Tin" into your TARG description. For fun, try Uranium. I have no idea what happens, nuclear fission? You can see a ton of gamma rays before Sim12 crashes.
