source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Fundamentals/unitSystem.xml@ 1324

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Changed by: Katsuya Amako, 14-Jul-1998                -->
<!--    Changed by: Katsuya Amako, 30-Nov-1998                -->
<!--    Changed by: Dennis Wright, 20-Nov-2001                -->
<!--    Proof read by: Joe Chuma,  28-Jun-1999                -->
<!--                                                          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.SysUni">
<title>
System of units
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.SysUni.BasicUni">
<title>
Basic units
</title>

<para>
Geant4 offers the user the possibility to choose and use the
preferred units for any quantity. In fact, Geant4 takes
care of the units. Internally a consistent set on units
based on the <literal>HepSystemOfUnits</literal> is used:

<informalexample>
<programlisting>
                millimeter              (mm)
                nanosecond              (ns)
                Mega electron Volt      (MeV)
                positron charge         (eplus)
                degree Kelvin           (kelvin)
                the amount of substance (mole)
                luminous intensity      (candela)
                radian                  (radian)
                steradian               (steradian)
</programlisting>
</informalexample>
</para>

<para>
All other units are defined from the basic ones.
</para>

<para>
For instance:

<informalexample>
<programlisting>
                 millimeter = mm = 1;
                 meter = m = 1000*mm;
                 ...
                 m3 = m*m*m;
                 ...
</programlisting>
</informalexample>
</para>

<para>
In the file
<literal>$CLHEP_BASE_DIR/include/CLHEP/Units/SystemOfUnits.h</literal>
from the CLHEP installation, one can find all untis definitions.
</para>

<para>
One can also change the system of units to be used by the kernel.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.SysUni.InputData">
<title>
Input your data
</title>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.SysUni.InputData.AvoidHardCoded">
<title>
Avoid 'hard coded' data
</title>

<para>
The user <emphasis role="bold">must</emphasis> give the units for the 
data to introduce:

<informalexample>
<programlisting>
 G4double Size = 15*km, KineticEnergy = 90.3*GeV, density = 11*mg/cm3;
</programlisting>
</informalexample>
</para>

<para>
Geant4 assumes that these specifications for the units are respected,
in order to assure indeipendence from the units chosen in the client
application.
</para>

<para>
If units are not specified in the client application, data are implicitly
treated in internal Geant4 system units; this practice is however strongly
discouraged.
</para>

<para>
If the data set comes from an array or from an external file, it
is strongly recommended to set the units as soon as the data are
read, before any treatment. For instance:

<informalexample>
<programlisting>
  for (int j=0, j&lt;jmax, j++) CrossSection[j] *= millibarn;
  ...
  my calculations
  ...
</programlisting>
</informalexample>
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.SysUni.InputData.Interactive">
<title>
Interactive commands
</title>

<para>
Some built-in commands from the User Interface (UI) also require
units to be specified.
</para>

<para>
For instance:

<informalexample>
<programlisting>
    /gun/energy 15.2 keV
    /gun/position 3 2 -7 meter
</programlisting>
</informalexample>
</para>

<para>
If units are not specified, or are not valid, the command is refused.
</para>

</sect3>
</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.SysUni.OutputData">
<title>
Output your data
</title>

<para>
You can output your data with the wished units. To do so, it is
sufficient to <emphasis role="bold">divide</emphasis> the data by the 
corresponding unit:

<informalexample>
<programlisting>     
      G4cout &lt;&lt; KineticEnergy/keV &lt;&lt; " keV";
      G4cout &lt;&lt; density/(g/cm3)   &lt;&lt; " g/cm3";
</programlisting>
</informalexample>     
</para>

<para>
Of course, <literal>G4cout &lt;&lt; KineticEnergy</literal> will print the
energy in the internal units system.
</para>

<para>
There is another way to output the data. Let Geant4 choose the
most appropriate units for the actual numerical value of the data.
It is sufficient to specify to which category the data belong to
(Length, Time, Energy, etc.). For example

<informalexample>
<programlisting>     
      G4cout &lt;&lt; G4BestUnit(StepSize, "Length");
</programlisting>
</informalexample>     
</para>

<para>
<literal>StepSize</literal> will be printed in km, m, mm, fermi, etc.
depending of its actual value.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.SysUni.IntroNewUnits">
<title>
Introduce new units
</title>

<para>
If wished to introduce new units, there are two methods:

<itemizedlist spacing="compact">
  <listitem><para>
    You can complete the file <literal>SystemOfUnits.h</literal>

    <informalexample>
    <programlisting>       
      #include "SystemOfUnits.h"
      
      static const G4double inch = 2.54*cm;
    </programlisting>
    </informalexample>      

    Using this method, it is not easy to define composed units. It
    is better to do the following:
  </para></listitem>
  <listitem><para>
    Instantiate an object of the class
    <emphasis>G4UnitDefinition</emphasis>

    <informalexample>
    <programlisting>       
      G4UnitDefinition ( name, symbol, category, value )
    </programlisting>
    </informalexample>       

    For example: define a few units for speed

    <informalexample>
    <programlisting>       
      G4UnitDefinition ( "km/hour" , "km/h", "Speed", km/(3600*s) );
      G4UnitDefinition ( "meter/ns", "m/ns", "Speed", m/ns );
    </programlisting>
    </informalexample>       

    The category "Speed" does not exist by default in
    <emphasis>G4UnitsTable</emphasis>, but it will be created automatically.
    The class <emphasis>G4UnitDefinition</emphasis> is located in
    <literal>source/global/management</literal>.
  </para></listitem>
</itemizedlist>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.SysUni.PrintUnits">
<title>
Print the list of units
</title>

<para>
You can print the list of units with the static function:
<literal>G4UnitDefinition::PrintUnitsTable();</literal>
</para>

<para>
or with the interactive command: <literal>/units/list</literal>
</para>


</sect2>
</sect1>