include/Geant4/G4Region.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 // G4Region
0027 //
0028 // Class description:
0029 //
0030 // Defines a region or a group of regions in the detector geometry
0031 // setup, sharing properties associated to materials or production
0032 // cuts which may affect or bias specific physics processes.
0033
0034 // Author: Gabriele Cosmo (CERN), 18.09.2002
0035 // --------------------------------------------------------------------
0036 #ifndef G4REGION_HH
0037 #define G4REGION_HH 1
0038
0039 #include <vector>
0040 #include <map>
0041 #include <algorithm>
0042
0043 #include "G4Types.hh"
0044 #include "G4String.hh"
0045 #include "G4GeomSplitter.hh"
0046
0047 class G4ProductionCuts;
0048 class G4LogicalVolume;
0049 class G4Material;
0050 class G4VUserRegionInformation;
0051 class G4MaterialCutsCouple;
0052 class G4UserLimits;
0053 class G4FieldManager;
0054 class G4FastSimulationManager;
0055 class G4VPhysicalVolume;
0056 class G4UserSteppingAction;
0057
0058 /**
0059  * @brief G4RegionData encapsulates the fields associated to the class
0060  * G4Region that may not be read-only..
0061  */
0062
0063 class G4RegionData
0064 {
0065   public:
0066
0067     void initialize()
0068     {
0069       fFastSimulationManager = nullptr;
0070       fRegionalSteppingAction = nullptr;
0071     }
0072
0073     G4FastSimulationManager* fFastSimulationManager;
0074     G4UserSteppingAction* fRegionalSteppingAction;
0075 };
0076
0077 // Encapsulate the methods used by both the master thread and worker threads
0078 // to allocate memory space for the fields encapsulated by the class
0079 // G4RegionData.
0080 //
0081 using G4RegionManager = G4GeomSplitter<G4RegionData>;
0082
0083 /**
0084  * @brief G4Region defines a region or a group of regions in the detector
0085  * geometry setup, sharing properties associated to materials or production
0086  * cuts which may affect or bias specific physics processes.
0087  */
0088
0089 class G4Region
0090 {
0091   public:
0092
0093     /**
0094      * Constructor for G4Region.
0095      *  @param[in] name The name of the region.
0096      */
0097     G4Region(const G4String& name);
0098
0099     /**
0100      * Destructor.
0101      */
0102     ~G4Region();
0103
0104     /**
0105      * Copy constructor and assignment operator not allowed.
0106      */
0107     G4Region(const G4Region&) = delete;
0108     G4Region& operator=(const G4Region&) = delete;
0109
0110     /**
0111      * Equality operator, defined by address only.
0112      */
0113     inline G4bool operator==(const G4Region& rg) const;
0114
0115     /**
0116      * Adds a root logical volume and sets its daughters flags as regions.
0117      * It also recompute the materials list for the region.
0118      * Search in the tree can be turned off, assuming the user guarantees
0119      * the logical volume is NOT already inserted, in which case significant
0120      * speedup can be achieved in complex flat geometry setups.
0121      *  @param[in] lv Pointer to the logical volume to act as root region.
0122      *  @param[in] search To enable/disable search in the tree (default true).
0123      */
0124     void AddRootLogicalVolume(G4LogicalVolume* lv, G4bool search=true);
0125
0126     /**
0127      * Removes a root logical volume and resets its daughters flags as regions.
0128      * It also recompute the materials list for the region.
0129      * The flag for scanning the subtree is always enabled by default.
0130      *  @param[in] lv Pointer to the logical volume to remove as root region.
0131      *  @param[in] scan To enable/disable scanning the tree (default true).
0132      */
0133     void RemoveRootLogicalVolume(G4LogicalVolume* lv, G4bool scan=true);
0134
0135     /**
0136      * Setter/getter for the region's name.
0137      */
0138     void SetName(const G4String& name);
0139     inline const G4String& GetName() const;
0140
0141     /**
0142      * Accessors to flag identifying if a region has been modified (and still
0143      * cuts needs to be computed) or not.
0144      */
0145     inline void RegionModified(G4bool flag);
0146     inline G4bool IsModified() const;
0147
0148     /**
0149      * Setter/getter for the production cuts values.
0150      */
0151     inline void SetProductionCuts(G4ProductionCuts* cut);
0152     inline G4ProductionCuts* GetProductionCuts() const;
0153
0154     /**
0155      * Methods to return iterators to the lists of root logical volumes
0156      * and materials.
0157      */
0158     inline std::vector<G4LogicalVolume*>::iterator
0159            GetRootLogicalVolumeIterator();
0160     inline std::vector<G4Material*>::const_iterator
0161            GetMaterialIterator() const;
0162
0163     /**
0164      * Methods to return the number of elements in the lists of materials and
0165      * root logical volumes.
0166      */
0167     inline std::size_t GetNumberOfMaterials() const;
0168     inline std::size_t GetNumberOfRootVolumes() const;
0169
0170     /**
0171      * Clears the material list and recomputes it, looping through each root
0172      * logical volume in the region.
0173      */
0174     void UpdateMaterialList();
0175
0176     /**
0177      * Clears the material list.
0178      */
0179     void ClearMaterialList();
0180
0181     /**
0182      * Scans recursively the 'lv' logical volume tree, retrieves and places
0183      * all materials in the list if becoming a region.
0184      */
0185     void ScanVolumeTree(G4LogicalVolume* lv, G4bool region);
0186
0187     /**
0188      * Setter/getter for the user information data.
0189      */
0190     inline void SetUserInformation(G4VUserRegionInformation* ui);
0191     inline G4VUserRegionInformation* GetUserInformation() const;
0192
0193     /**
0194      * Setter/getter for the user-limits associated to a region.
0195      * Once user-limits are set, it will propagate to the daughter volumes.
0196      */
0197     inline void SetUserLimits(G4UserLimits* ul);
0198     inline G4UserLimits* GetUserLimits() const;
0199
0200     /**
0201      * Resets the material-cuts-couples map.
0202      */
0203     inline void ClearMap();
0204
0205     /**
0206      * Method invoked by G4ProductionCutsTable to register the material-cuts
0207      * couple pair.
0208      */
0209     inline void RegisterMaterialCouplePair(G4Material* mat,
0210                                            G4MaterialCutsCouple* couple);
0211
0212     /**
0213      * Finds a G4MaterialCutsCouple which corresponds to the material 'mat'
0214      * in the region.
0215      */
0216     inline G4MaterialCutsCouple* FindCouple(G4Material* mat);
0217
0218     /**
0219      * Setter/getter for the fast-simulation manager. The root logical volume
0220      * that has the region with G4FastSimulationManager becomes an envelope of
0221      * fast simulation.
0222      */
0223     void SetFastSimulationManager(G4FastSimulationManager* fsm);
0224     G4FastSimulationManager* GetFastSimulationManager() const;
0225
0226     /**
0227      * Sets the G4FastSimulationManager pointer to the one for the parent
0228      * region if it exists, otherwise it sets it to null.
0229      */
0230     void ClearFastSimulationManager();
0231
0232     /**
0233      * Setter/getter for the field manager. The region with assigned
0234      * field-manager sets the field to the geometrical area associated with
0235      * it; priority is anyhow given to local fields eventually set to logical
0236      * volumes.
0237      */
0238     inline void SetFieldManager(G4FieldManager* fm);
0239     inline G4FieldManager* GetFieldManager() const;
0240
0241     /**
0242      * Get method for the world physical volume which the region belongs to.
0243      * A valid pointer will be assigned by G4RunManagerKernel through the
0244      * G4RegionStore when the geometry is to be closed. Thus, this pointer
0245      * may be incorrect at the PreInit and Idle state. If the pointer is null
0246      * at the proper state, this particular region does not belong to any
0247      * world (maybe not assigned to any volume, etc.).
0248      */
0249     inline G4VPhysicalVolume* GetWorldPhysical() const;
0250
0251     /**
0252      * Sets the world physical volume if the region belongs to this world.
0253      * If 'wp' pointer is null, resets the pointer.
0254      */
0255     void SetWorld(G4VPhysicalVolume* wp);
0256
0257     /**
0258      * Returns whether the region belongs to the given physical volume 'pv'
0259      * (recursively scanned to the bottom of the hierarchy).
0260      */
0261     G4bool BelongsTo(G4VPhysicalVolume* pv) const;
0262
0263     /**
0264      * Returns a region that contains this region. Otherwise null returned.
0265      *  @param[out] unique Returns true if there is only one parent region
0266      *              containing the current region.
0267      *  @returns A pointer to the mother region.
0268      */
0269     G4Region* GetParentRegion(G4bool& unique) const;
0270
0271     /**
0272      * Setter/getter methods for the regional user stepping action.
0273      */
0274     void SetRegionalSteppingAction(G4UserSteppingAction* rusa);
0275     G4UserSteppingAction* GetRegionalSteppingAction() const;
0276
0277     /**
0278      * Fake default constructor for usage restricted to direct object
0279      * persistency for clients requiring preallocation of memory for
0280      * persistifiable objects.
0281      */
0282     G4Region(__void__&);
0283
0284     /**
0285      * Returns the instance ID for multi-threading.
0286      */
0287     inline G4int GetInstanceID() const;
0288
0289     /**
0290      * Returns the private data instance manager for multi-threading.
0291      */
0292     static const G4RegionManager& GetSubInstanceManager();
0293
0294     /**
0295      * Clears the memory allocated by the MT sub-instance manager.
0296      */
0297     static void Clean();
0298
0299     /**
0300      * Utility methods to identify if the region is part of the main mass
0301      * geometry for tracking or part of a parallel geometry.
0302      */
0303     inline void UsedInMassGeometry(G4bool val = true);
0304     inline void UsedInParallelGeometry(G4bool val = true);
0305     inline G4bool IsInMassGeometry() const;
0306     inline G4bool IsInParallelGeometry() const;
0307
0308   private:
0309
0310     /**
0311      * Searchs the specified material 'aMaterial' in the material table and
0312      * if not present adds it.
0313      */
0314     inline void AddMaterial (G4Material* aMaterial);
0315
0316   private:
0317
0318     using G4RootLVList = std::vector<G4LogicalVolume*>;
0319     using G4MaterialList = std::vector<G4Material*>;
0320     using G4MaterialCouplePair = std::pair<G4Material*, G4MaterialCutsCouple*>;
0321     using G4MaterialCoupleMap = std::map<G4Material*, G4MaterialCutsCouple*>;
0322
0323     G4String fName;
0324
0325     G4RootLVList fRootVolumes;
0326     G4MaterialList fMaterials;
0327     G4MaterialCoupleMap fMaterialCoupleMap;
0328
0329     G4bool fRegionMod = true;
0330     G4ProductionCuts* fCut = nullptr;
0331
0332     G4VUserRegionInformation* fUserInfo = nullptr;
0333     G4UserLimits* fUserLimits = nullptr;
0334     G4FieldManager* fFieldManager = nullptr;
0335
0336     G4VPhysicalVolume* fWorldPhys = nullptr;
0337
0338     G4bool fInMassGeometry = false;
0339     G4bool fInParallelGeometry = false;
0340
0341     /** This field is used as instance ID. */
0342     G4int instanceID;
0343
0344     /** This field helps to use the class G4RegionManager introduced above. */
0345     G4GEOM_DLL static G4RegionManager subInstanceManager;
0346 };
0347
0348 #include "G4Region.icc"
0349
0350 // NOTE:
0351 //
0352 // The type G4RegionManager is introduced to encapsulate the methods used by
0353 // both the master thread and worker threads to allocate memory space for
0354 // the fields encapsulated by the class G4RegionData. When each thread
0355 // initializes the value for these fields, it refers to them using a macro
0356 // definition defined below. For every G4Region instance, there is a
0357 // corresponding G4RegionData instance. All G4RegionData instances are
0358 // organized by the class G4RegionManager as an array.
0359 // The field "int instanceID" is added to the class G4Region.
0360 // The value of this field in each G4Region instance is the subscript
0361 // of the corresponding G4RegionData instance.
0362 // In order to use the class G4RegionManager, we add a static member in
0363 // the class G4Region as follows: "static G4RegionManager subInstanceManager".
0364 // For the master thread, the array for G4RegionData instances grows
0365 // dynamically along with G4Region instances are created. For each worker
0366 // thread, it copies the array of G4RegionData instances from the master thread.
0367 // In addition, it invokes a method similiar to the constructor explicitly
0368 // to achieve the partial effect for each instance in the array.
0369
0370 #endif