include/Geant4/G4MolecularConfiguration.hh

0001 //
0002 // ********************************************************************
0003 // * License and Disclaimer                                           *
0004 // *                                                                  *
0005 // * The  Geant4 software  is  copyright of the Copyright Holders  of *
0006 // * the Geant4 Collaboration.  It is provided  under  the terms  and *
0007 // * conditions of the Geant4 Software License,  included in the file *
0008 // * LICENSE and available at  http://cern.ch/geant4/license .  These *
0009 // * include a list of copyright holders.                             *
0010 // *                                                                  *
0011 // * Neither the authors of this software system, nor their employing *
0012 // * institutes,nor the agencies providing financial support for this *
0013 // * work  make  any representation or  warranty, express or implied, *
0014 // * regarding  this  software system or assume any liability for its *
0015 // * use.  Please see the license in the file  LICENSE  and URL above *
0016 // * for the full disclaimer and the limitation of liability.         *
0017 // *                                                                  *
0018 // * This  code  implementation is the result of  the  scientific and *
0019 // * technical work of the GEANT4 collaboration.                      *
0020 // * By using,  copying,  modifying or  distributing the software (or *
0021 // * any work based  on the software)  you  agree  to acknowledge its *
0022 // * use  in  resulting  scientific  publications,  and indicate your *
0023 // * acceptance of all terms of the Geant4 Software license.          *
0024 // ********************************************************************
0025 //
0026 //
0027 // Author: Mathieu Karamitros
0028
0029 // The code is developed in the framework of the ESA AO7146
0030 //
0031 // We would be very happy hearing from you, send us your feedback! :)
0032 //
0033 // In order for Geant4-DNA to be maintained and still open-source,
0034 // article citations are crucial.
0035 // If you use Geant4-DNA chemistry and you publish papers about your software,
0036 // in addition to the general paper on Geant4-DNA:
0037 //
0038 // Int. J. Model. Simul. Sci. Comput. 1 (2010) 157–178
0039 //
0040 // we would be very happy if you could please also cite the following
0041 // reference papers on chemistry:
0042 //
0043 // J. Comput. Phys. 274 (2014) 841-882
0044 // Prog. Nucl. Sci. Tec. 2 (2011) 503-508
0045
0046 #ifndef G4MolecularConfiguration_
0047 #define G4MolecularConfiguration_ 1
0048
0049 #include <vector>
0050 #include <map>
0051 #include "G4Threading.hh"
0052 #include "G4ElectronOccupancy.hh"
0053 #include <cassert>
0054 #include <functional>
0055
0056 class G4MolecularDissociationChannel;
0057 class G4MoleculeDefinition;
0058 class G4Material;
0059 class G4MolecularConfiguration;
0060
0061 struct comparator
0062 {
0063   bool operator()(const G4ElectronOccupancy& occ1,
0064                   const G4ElectronOccupancy& occ2) const
0065   {
0066     G4int totalOcc1 = occ1.GetTotalOccupancy();
0067     G4int totalOcc2 = occ2.GetTotalOccupancy();
0068     if (totalOcc1 != totalOcc2)
0069     {
0070       return totalOcc1 < totalOcc2;
0071     }
0072
0073     G4int occupancy1 = -1;
0074     G4int occupancy2 = -1;
0075     const G4int sizeOrbit = occ1.GetSizeOfOrbit();
0076     for (G4int i = 0; i < sizeOrbit; i++)
0077     {
0078       occupancy1 = occ1.GetOccupancy(i);
0079       occupancy2 = occ2.GetOccupancy(i);
0080
0081       if (occupancy1 != occupancy2)
0082       {
0083         return occupancy1 < occupancy2;
0084       }
0085     }
0086
0087     return false;
0088   }
0089 };
0090
0091 /** The pointer G4MolecularConfiguration will be shared by all the
0092  * molecules having the same molecule definition and the same
0093  * electron occupancy
0094  * BE CAREFUlL !!! : If you change the mass for instance of a OH^-,
0095  * this will affect all the OH^- molecule diffusing around
0096  */
0097 class G4MolecularConfiguration
0098 {
0099 public:
0100
0101   using G4DiffCoeffParam = std::function<double (const G4Material *, double, const G4MolecularConfiguration *)>;
0102
0103   //____________________________________________________________________________
0104   // Static methods
0105
0106   /////////////////////////////////////////////////
0107   // CREATE FINALIZED SPECIES
0108   // Get ground state electronic configuration
0109   static G4MolecularConfiguration*
0110   GetOrCreateMolecularConfiguration(const G4MoleculeDefinition*);
0111
0112   // Get for a given moleculeDefinition and a given electronic configuration,
0113   // the molecular configuration
0114   static G4MolecularConfiguration*
0115   GetOrCreateMolecularConfiguration(const G4MoleculeDefinition*,
0116                                     const G4ElectronOccupancy& eOcc);
0117
0118   // Get for a given moleculeDefinition and a given electronic configuration,
0119   // the molecular configuration
0120   static G4MolecularConfiguration*
0121   GetOrCreateMolecularConfiguration(const G4MoleculeDefinition*, int charge);
0122
0123   /////////////////////////////////////////////////
0124   // CREATE UNFINALIZED SPECIES
0125   // Create ground state electronic configuration - to be finalized
0126   static G4MolecularConfiguration*
0127     CreateMolecularConfiguration(const G4String& userIdentifier,
0128                                  const G4MoleculeDefinition*,
0129                                  bool& wasAlreadyCreated);
0130
0131   static G4MolecularConfiguration*
0132     CreateMolecularConfiguration(const G4String& userIdentifier,
0133                                  const G4MoleculeDefinition*,
0134                                  const G4String& label,
0135                                  const G4ElectronOccupancy& eOcc,
0136                                  bool& wasAlreadyCreated);
0137
0138   static G4MolecularConfiguration*
0139     CreateMolecularConfiguration(const G4String& userIdentifier,
0140                                  const G4MoleculeDefinition*,
0141                                  int charge,
0142                                  const G4String& label,
0143                                  bool& wasAlreadyCreated);
0144
0145   static G4MolecularConfiguration*
0146     CreateMolecularConfiguration(const G4String& userIdentifier,
0147                                  const G4MoleculeDefinition*,
0148                                  const G4String& label,
0149                                  bool& wasAlreadyCreated);
0150
0151   /////////////////////////////////////////////////
0152   // GET MOL CONF
0153   //
0154   static G4MolecularConfiguration*
0155     GetMolecularConfiguration(const G4MoleculeDefinition*,
0156                               const G4String& label);
0157
0158   static G4MolecularConfiguration*
0159     GetMolecularConfiguration(int moleculeID);
0160
0161   static G4MolecularConfiguration*
0162     GetMolecularConfiguration(const G4String& userID);
0163
0164   static int GetNumberOfSpecies();
0165
0166   static std::map<G4String, G4MolecularConfiguration*>& GetUserIDTable()
0167   {
0168     return GetManager()->GetUserIDTable();
0169   }
0170
0171   // Release memory of the mol conf manager
0172   static void DeleteManager();
0173
0174   static double DiffCoeffWater(double temperature_K);
0175
0176   void AddDiffCoeffParameterization(const G4DiffCoeffParam&);
0177
0178   //____________________________________________________________________________
0179
0180   const G4MoleculeDefinition* GetDefinition() const;
0181
0182   /** Returns the name of the molecule
0183    */
0184   const G4String& GetName() const;
0185
0186   /** Returns the formated name of the molecule
0187    */
0188   const G4String& GetFormatedName() const;
0189
0190   /** Returns the nomber of atoms compouning the molecule
0191    */
0192   G4int GetAtomsNumber() const;
0193
0194   /** Method used in Geant4-DNA to excite water molecules
0195    */
0196   G4MolecularConfiguration* ExciteMolecule(G4int) const;
0197
0198   /** Method used in Geant4-DNA to ionize water molecules
0199    */
0200   G4MolecularConfiguration* IonizeMolecule(G4int) const;
0201
0202   /** Add n electrons to a given orbit.
0203    * Note : You can add as many electrons to a given orbit, the result
0204    * may be unrealist.
0205    */
0206   G4MolecularConfiguration* AddElectron(G4int orbit, G4int n = 1) const;
0207
0208   /** Remove n electrons to a given orbit.
0209    */
0210   G4MolecularConfiguration* RemoveElectron(G4int, G4int number = 1) const;
0211
0212   /** Move one electron from an orbit to another.
0213    */
0214   G4MolecularConfiguration* MoveOneElectron(G4int /*orbit*/, G4int /*orbit*/) const;
0215
0216   /** Returns the number of electron.
0217    */
0218   G4double GetNbElectrons() const;
0219
0220   /** Display the electronic state of the molecule.
0221    */
0222   void PrintState() const;
0223
0224   const std::vector<const G4MolecularDissociationChannel*>* GetDissociationChannels() const;
0225
0226   G4int GetFakeParticleID() const;
0227
0228   inline G4int GetMoleculeID() const;
0229
0230   /** Sets the diffusion coefficient D of the molecule used in diffusion
0231    * processes to calculate the mean square jump distance between two
0232    * changes of direction. In three dimension : <x^2> = 6 D t where t is
0233    * the mean jump time between two changes of direction.
0234    *
0235    * Note : Diffusion Coefficient in one medium only
0236    * For the time being, we will consider only one diffusion
0237    * coefficient for the all simulation => diffusion in one medium only
0238    * If the user needs to use the diffusion in different materials,
0239    * she/he should contact the developers/maintainers of this package
0240    */
0241   inline void SetDiffusionCoefficient(G4double);
0242
0243   /** Returns the diffusion coefficient D.
0244    */
0245   inline G4double GetDiffusionCoefficient() const;
0246
0247   inline G4double GetDiffusionCoefficient(const G4Material*,
0248                                           double temperature) const;
0249
0250   /** Set the decay time of the molecule.
0251    */
0252   inline void SetDecayTime(G4double);
0253
0254   /** Returns the decay time of the molecule.
0255    */
0256   inline G4double GetDecayTime() const;
0257
0258   /** The Van Der Valls Radius of the molecule
0259    */
0260   inline void SetVanDerVaalsRadius(G4double);
0261   inline G4double GetVanDerVaalsRadius() const;
0262
0263   /** Returns the object ElectronOccupancy describing the electronic
0264    * configuration of the molecule.
0265    */
0266   inline const G4ElectronOccupancy* GetElectronOccupancy() const;
0267
0268   /** Returns the charge of molecule.
0269    */
0270   inline G4int GetCharge() const;
0271
0272   /** Set the total mass of the molecule.
0273    */
0274   inline void SetMass(G4double);
0275
0276   /** Returns the total mass of the molecule.
0277    */
0278   inline G4double GetMass() const;
0279
0280   /*
0281    * Adds a label to the molecular configuration
0282    * (Can be used for vibrational states for instance)
0283    */
0284   inline void SetLabel(const G4String&);
0285
0286   /*
0287    * Returns the label assigned by the user
0288    */
0289   inline const G4String& GetLabel() const;
0290
0291   inline void Finalize();
0292   static void FinalizeAll();
0293   static void PrintAll(); //hoang added
0294   inline void UnFinalize();
0295   void SetUserID(const G4String& userID);//hoang moved it to public
0296
0297   inline const G4String& GetUserID() const;
0298
0299   static void SetGlobalTemperature(G4double);
0300   static G4double GetGlobalTemperature();
0301
0302   //___________________________________________________________________________
0303   // EXPERIMENTAL
0304
0305   static G4MolecularConfiguration* Load(std::istream&);
0306
0307   void Serialize(std::ostream&);
0308   void Unserialize(std::istream&);
0309   //___________________________________________________________________________
0310
0311
0312 protected:
0313   G4MolecularConfiguration(const G4MoleculeDefinition*,
0314                            const G4ElectronOccupancy&,
0315                            const G4String& label = "");
0316
0317   G4MolecularConfiguration(const G4MoleculeDefinition*,
0318                            int charge);
0319
0320   G4MolecularConfiguration(const G4MoleculeDefinition*,
0321                            const G4String& label,
0322                            int charge);
0323
0324   G4MolecularConfiguration(std::istream&);
0325
0326   G4MolecularConfiguration(const G4MolecularConfiguration&);
0327   G4MolecularConfiguration & operator=(G4MolecularConfiguration &right);
0328   ~G4MolecularConfiguration();
0329   G4MolecularConfiguration* ChangeConfiguration(const G4ElectronOccupancy& newElectronOccupancy) const;
0330   G4MolecularConfiguration* ChangeConfiguration(int charge) const;
0331
0332   void CheckElectronOccupancy(const char* line) const;
0333   void MakeExceptionIfFinalized();
0334
0335   void CreateDefaultDiffCoeffParam();
0336   static void ScaleAllDiffusionCoefficientsOnWater(double temperature_K);
0337
0338 public:
0339   class G4MolecularConfigurationManager
0340   {
0341   public:
0342     G4MolecularConfigurationManager()
0343     {
0344       fLastMoleculeID = -1;
0345     }
0346     ~G4MolecularConfigurationManager();
0347
0348     int GetNumberOfCreatedSpecies()
0349     {
0350       return fLastMoleculeID+1;
0351     }
0352
0353     //------------------------------------------------------------------------
0354     // CALLED FROM CONSTRUCTORS
0355     G4int Insert(const G4MoleculeDefinition* molDef,
0356                  const G4ElectronOccupancy& eOcc,
0357                  G4MolecularConfiguration* molConf);
0358
0359     G4int Insert(const G4MoleculeDefinition* molDef,
0360                  int charge,
0361                  G4MolecularConfiguration* molConf);
0362
0363     G4int Insert(const G4MoleculeDefinition* molDef,
0364                  const G4String& label,
0365                  G4MolecularConfiguration* molConf);
0366
0367     //------------------------------------------------------------------------
0368     // CALLED WHEN USER ADD SPECIES
0369     void AddUserID(const G4String& name,
0370                    G4MolecularConfiguration* molecule);
0371
0372     void RecordNewlyLabeledConfiguration(G4MolecularConfiguration* molConf);
0373
0374     const G4ElectronOccupancy*
0375       FindCommonElectronOccupancy(const G4MoleculeDefinition* molDef,
0376                                   const G4ElectronOccupancy& eOcc);
0377
0378     G4MolecularConfiguration*
0379       GetMolecularConfiguration(const G4MoleculeDefinition* molDef,
0380                                 const G4ElectronOccupancy& eOcc);
0381
0382     G4MolecularConfiguration*
0383       GetMolecularConfiguration(const G4MoleculeDefinition* molDef,
0384                                 int charge);
0385
0386     G4MolecularConfiguration*
0387       GetMolecularConfiguration(const G4MoleculeDefinition* molDef,
0388                                 const G4String& label);
0389
0390     G4MolecularConfiguration* GetMolecularConfiguration(int moleculeID);
0391
0392     G4MolecularConfiguration* GetMolecularConfiguration(const G4String& userID);
0393
0394     G4MolecularConfiguration*
0395       GetOrCreateMolecularConfiguration(const G4MoleculeDefinition* molDef,
0396                                         const G4ElectronOccupancy& eOcc);
0397
0398     G4MolecularConfiguration*
0399       GetOrCreateMolecularConfiguration(const G4MoleculeDefinition* molDef,
0400                                         int charge);
0401
0402     static G4Mutex fManagerCreationMutex;
0403
0404     void RemoveMolecularConfigurationFromTable(G4MolecularConfiguration*);
0405
0406     const std::vector<G4MolecularConfiguration*>& GetAllSpecies()
0407     {
0408       return fMolConfPerID;
0409     }
0410
0411     std::map<G4String, G4MolecularConfiguration*>& GetUserIDTable()
0412     {
0413       return fUserIDTable;
0414     }
0415
0416   private:
0417
0418     //__________________________________________________________________________
0419     using ElectronOccupancyTable = std::map<G4ElectronOccupancy, G4MolecularConfiguration *, comparator>;
0420     using MolElectronConfTable = std::map<const G4MoleculeDefinition *, ElectronOccupancyTable>;
0421     MolElectronConfTable fElecOccTable;
0422
0423     //__________________________________________________________________________
0424     using ChargeTable = std::map<int, G4MolecularConfiguration *>;
0425     using MolChargeConfTable = std::map<const G4MoleculeDefinition *, ChargeTable>;
0426     MolChargeConfTable fChargeTable;
0427
0428     //__________________________________________________________________________
0429     using LabelTable = std::map<const G4String, G4MolecularConfiguration *>;
0430     using MolLabelConfTable = std::map<const G4MoleculeDefinition *, std::map<const G4String, G4MolecularConfiguration *>>;
0431     MolLabelConfTable fLabelTable;
0432
0433     //__________________________________________________________________________
0434     using UserIDTable = std::map<G4String, G4MolecularConfiguration *>;
0435     UserIDTable fUserIDTable;
0436
0437     //__________________________________________________________________________
0438     std::vector<G4MolecularConfiguration*> fMolConfPerID;
0439     // Indexed by molecule ID
0440
0441     //__________________________________________________________________________
0442     G4int fLastMoleculeID;
0443     G4Mutex fMoleculeCreationMutex;
0444   };
0445
0446 protected:
0447   static G4MolecularConfigurationManager* fgManager;
0448   static G4MolecularConfigurationManager* GetManager();
0449
0450   const G4MoleculeDefinition* fMoleculeDefinition;
0451   const G4ElectronOccupancy* fElectronOccupancy;
0452
0453   mutable G4String* fLabel;
0454
0455   G4double fDynDiffusionCoefficient;
0456   G4double fDynVanDerVaalsRadius;
0457   G4double fDynDecayTime;
0458   G4double fDynMass;
0459   G4int fDynCharge;
0460   G4int fMoleculeID;
0461   /*mutable*/ G4String fFormatedName;
0462   /*mutable*/ G4String fName;
0463   G4String fUserIdentifier;
0464   G4bool fIsFinalized;
0465
0466   G4DiffCoeffParam fDiffParam;
0467   static /*G4ThreadLocal*/double fgTemperature;
0468
0469   static double ReturnDefaultDiffCoeff(const G4Material*,
0470                                        double,
0471                                        const G4MolecularConfiguration*
0472                                        molConf);
0473 };
0474
0475 inline const G4MoleculeDefinition* G4MolecularConfiguration::GetDefinition() const
0476 {
0477   return fMoleculeDefinition;
0478 }
0479
0480 inline const G4ElectronOccupancy* G4MolecularConfiguration::GetElectronOccupancy() const
0481 {
0482   return fElectronOccupancy;
0483 }
0484
0485 inline void G4MolecularConfiguration::SetDiffusionCoefficient(G4double dynDiffusionCoefficient)
0486 {
0487   MakeExceptionIfFinalized();
0488   fDynDiffusionCoefficient = dynDiffusionCoefficient;
0489 }
0490
0491 inline G4double G4MolecularConfiguration::GetDiffusionCoefficient() const
0492 {
0493   return fDynDiffusionCoefficient;
0494 }
0495
0496 inline void G4MolecularConfiguration::SetDecayTime(G4double dynDecayTime)
0497 {
0498   MakeExceptionIfFinalized();
0499   fDynDecayTime = dynDecayTime;
0500 }
0501
0502 inline G4double G4MolecularConfiguration::GetDecayTime() const
0503 {
0504   return fDynDecayTime;
0505 }
0506
0507 inline void G4MolecularConfiguration::SetVanDerVaalsRadius(G4double dynVanDerVaalsRadius)
0508 {
0509   MakeExceptionIfFinalized();
0510   fDynVanDerVaalsRadius = dynVanDerVaalsRadius;
0511 }
0512
0513 inline G4double G4MolecularConfiguration::GetVanDerVaalsRadius() const
0514 {
0515   return fDynVanDerVaalsRadius;
0516 }
0517
0518 inline G4int G4MolecularConfiguration::GetCharge() const
0519 {
0520   return fDynCharge;
0521 }
0522
0523 inline void G4MolecularConfiguration::SetMass(G4double aMass)
0524 {
0525   MakeExceptionIfFinalized();
0526   fDynMass = aMass;
0527 }
0528
0529 inline G4double G4MolecularConfiguration::GetMass() const
0530 {
0531   return fDynMass;
0532 }
0533
0534 inline G4int G4MolecularConfiguration::GetMoleculeID() const
0535 {
0536   return fMoleculeID;
0537 }
0538
0539 inline void G4MolecularConfiguration::SetLabel(const G4String& label)
0540 {
0541   assert(fLabel == 0 || *fLabel == "");
0542   if(fLabel == nullptr)
0543   {
0544     fLabel = new G4String(label);
0545   }
0546   else
0547   {
0548     *fLabel = label;
0549   }
0550   fgManager->RecordNewlyLabeledConfiguration(this);
0551 }
0552
0553 inline const G4String& G4MolecularConfiguration::GetLabel() const
0554 {
0555   if(fLabel == nullptr)
0556     fLabel = new G4String();
0557
0558   return (*fLabel);
0559 }
0560
0561 inline void G4MolecularConfiguration::Finalize()
0562 {
0563   CreateDefaultDiffCoeffParam();
0564   fIsFinalized = true;
0565 }
0566
0567 inline const G4String& G4MolecularConfiguration::GetUserID() const
0568 {
0569   return fUserIdentifier;
0570 }
0571
0572 inline void G4MolecularConfiguration::AddDiffCoeffParameterization
0573 (const G4DiffCoeffParam& para)
0574 {
0575   fDiffParam = para;
0576 }
0577
0578 inline G4double
0579 G4MolecularConfiguration::GetDiffusionCoefficient(const G4Material* material,
0580                                                   double temperature) const
0581 {
0582   return fDiffParam(material, temperature, this);
0583 }
0584
0585 inline void G4MolecularConfiguration::UnFinalize()
0586 {
0587   fIsFinalized = false;
0588 }
0589
0590 #endif