source: trunk/documents/UserDoc/DocBookUsersGuides/ForToolkitDeveloper/xml/GuideToExtendFunctionality/ElectromagneticField/electroMagneticField.xml@ 1291

<!-- ******************************************************** -->
<!--  Docbook Version:  For Toolkit Developers Guide          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.ExtdFuncEMFld">
<title>
Electromagnetic Fields
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncEMFld.CrtNwFld">
<title>
Creating a New Type of Field
</title>

<para>
Geant4 currently handles magnetic and electric fields and,
in future releases, will handle combined electromagnetic 
fields.  Fields due to other forces, not yet included in 
Geant4, can be provided by describing the new field and the
force it exerts on a particle passing through it.  For the
time being, all fields must be time-independent. This 
restriction may be lifted in the future. 
</para>

<para>
In order to accommodate a new type of field, two classes must 
be created: a field type and a class that determines the force. 
The Geant4 system must then be informed of the new field. 
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
A new Field class
</bridgehead>

<para>
A new type of Field class may be created by inheriting from 
G4Field 

<informalexample><programlisting>
      class NewField : public G4Field
      {
         public: 
            void  GetFieldValue( const  double Point[3],
                                        double *pField )=0;
      }
</programlisting></informalexample>

and deciding how many components your field will have, and what 
each component represents.  For example, three components are
required to describe a vector field while only one component is
required to describe a scalar field.
</para>

<para>
If you want your field to be a combination of different fields, 
you must choose your convention for which field goes first,
which second etc. For example, to define an electromagnetic field we 
follow the convention that components 0,1 and 2 refer to the magnetic
field and components 3, 4 and 5 refer to the electric field. 
</para>

<para>
By leaving the GetFieldValue method pure virtual, you force 
those users who want to describe their field to create a
class that implements it for their detector's instance of 
this field. So documenting what each component means is required,
to give them the necessary information. 
</para>

<para>
For example someone can describe DetectorAbc's field by creating 
a class DetectorAbcField, that derives from your NewField 

<informalexample><programlisting>
class DetectorAbcField : public NewField 
{
  public:
     void  MyFieldGradient::GetFieldValue( const double Point[3], 
                                           double *pField );
}
</programlisting></informalexample>

They then implement the function GetFieldValue 

<informalexample><programlisting>
      void  MyFieldGradient::GetFieldValue( const  double Point[3],
                                            double *pField )
      {
         // We expect pField to point to pField[9]; 
         // This &amp; the order of the components of pField is your own 
         // convention
       
         // We calculate the value of pField at Point ...
      }
</programlisting></informalexample>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
A new Equation of Motion for the new Field
</bridgehead>

<para>
Once you have created a new type of field, you must create an 
Equation of Motion for this Field. This is required in order to
obtain the force that a particle feels. 
</para>

<para>
To do this you must inherit from G4Mag_EqRhs and create your own 
equation of motion that understands your field. In it
you must implement the virtual function EvaluateRhsGivenB. Given 
the value of the field, this function calculates the
value of the generalised force. This is the only function that 
a subclass must define. 

<informalexample><programlisting>
     virtual void EvaluateRhsGivenB( const  G4double y[],
                              const  G4double B[3],
                                     G4double dydx[] ) const = 0;
</programlisting></informalexample>
</para>

<para>
In particular, the derivative vector dydx is a vector with six 
components. The first three are the derivative of the position
with respect to the curve length. Thus they should set equal to 
the normalised velocity, which is components 3, 4 and 5 of y. 

<informalexample><programlisting>
  (dydx[0], dydx[1], dydx[2]) = (y[3], y[4], y[5])
</programlisting></informalexample>
</para>

<para>
The next three components are the derivatives of the velocity 
vector with respect to the path length. So you should write the
"force" components for 

<informalexample><programlisting>
      dydx[3], dydx[4] and dydx[5]
</programlisting></informalexample>

for your field. 
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Get a G4FieldManager to use your field
</bridgehead>

<para>
In order to inform the Geant4 system that you want it to use 
your field as the global field, you must do the following steps: 

<orderedlist spacing="compact">
  <listitem><para>
    Create a Stepper of your choice: 
    <informalexample><programlisting>
       
      yourStepper = new G4ClassicalRK( yourEquationOfMotion );
                // or if your field is not smooth eg
                //     new G4ImplicitEuler( yourEquationOfMotion );
    </programlisting></informalexample>
  </para></listitem>
  <listitem><para>
    Create a chord finder that uses your Field and Stepper. You
    must also give it a minimum step size, below which it
    does not make sense to attempt to integrate: 
    <informalexample><programlisting>
      yourChordFinder= new G4ChordFinder( yourField,
                                 yourMininumStep, // say 0.01*mm
                                 yourStepper );
    </programlisting></informalexample>
  </para></listitem>
  <listitem><para>
    Next create a G4FieldManager and give it that chord finder, 
    <informalexample><programlisting>
      yourFieldManager= new G4FieldManager();
      yourFieldManager.SetChordFinder(yourChordFinder);
    </programlisting></informalexample>
  </para></listitem>
  <listitem><para>
    Finally we tell the Geometry that this FieldManager is 
    responsible for creating a field for the detector. 
    <informalexample><programlisting>
      G4TransportationManager::GetTransportationManager()
                            -> SetFieldManager( yourFieldManager );
    </programlisting></informalexample>
  </para></listitem>
</orderedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Changes for non-electromagnetic fields
</bridgehead>

<para>
If the field you are interested in simulating is not electromagnetic, 
another minor modification may be required. The
transportation currently chooses whether to propagate a particle 
in a field or rectilinearly based on whether the particle is
charged or not. If your field affects non-charged particles, you 
must inherit from the G4Transportation and re-implement the
part of GetAlongStepPhysicalInteractionLength that decides whether 
the particles is affected by your force. 
</para>

<para>
In particular the relevant section of code does the following: 

<informalexample><programlisting>
  //  Does the particle have an (EM) field force exerting upon it?
  //
  if( (particleCharge!=0.0) ){
     
     fieldExertsForce= this->DoesGlobalFieldExist();
     // Future: will/can also check whether current volume's field is Zero or
     //  set by the user (in the logical volume) to be zero.
  }
</programlisting></informalexample>

and you want it to ask whether it feels your force. If, for the sake 
of an example, you wanted to see the effects of gravity on a
heavy hypothetical particle, you could say 

<informalexample><programlisting>
  
  //  Does the particle have my field's force exerted on it?
  //
  if (particle->GetName() == "VeryHeavyWIMP") {
     fieldExertsForce= this->DoesGlobalFieldExist();  // For gravity
  }
</programlisting></informalexample>

After doing all these steps, you will be able to see the effects of 
your force on a particle's motion. 
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead role="revisionHistory" renderas="sect4">
[Status of this chapter]
</bridgehead>
<para>
<simplelist type="var">
  <member>
    10.06.02 partially re-written by D.H. Wright
  </member>
  <member>
    14.11.02 spell check by P. Arce
  </member>
    Dec. 2006 Conversion from latex to Docbook verson by K. Amako
  <member>
  </member>
</simplelist>
</para>
    

</sect2>
</sect1>