include/Geant4/G4SmartVoxelHeader.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 // G4SmartVoxelHeader
0027 //
0028 // Class description:
0029 //
0030 // Represents a set of voxels, created by a single axis of virtual division.
0031 // Contains the individual voxels, which are potentially further divided
0032 // along different axes.
0033 //
0034 // Member data:
0035 //
0036 // EAxis faxis
0037 //   - The (cartesian) slicing/division axis
0038 // G4double fmaxExtent
0039 // G4double fminExtent
0040 //   - Minimum and maximum coordiantes along the axis
0041 // std::vector<G4SmartVoxelProxy*> fslices
0042 //   - The slices along the axis
0043 //
0044 // G4int fminEquivalent
0045 // G4int fmaxEquivalent
0046 //   - Minimum and maximum equivalent slice nos.
0047 //     [Applies to the level of the header, not its nodes]
0048
0049 // Author: Paul Kent (CERN), 13.07.1995 - Initial version
0050 //         Gabriele Cosmo (CERN), 18.04.2001 - Migrated to STL vector
0051 // --------------------------------------------------------------------
0052 #ifndef G4SMARTVOXELHEADER_HH
0053 #define G4SMARTVOXELHEADER_HH
0054
0055 #include <vector>
0056
0057 #include "G4Types.hh"
0058 #include "geomdefs.hh"
0059
0060 #include "G4SmartVoxelProxy.hh"
0061 #include "G4SmartVoxelNode.hh"
0062
0063 // Forward declarations
0064 class G4LogicalVolume;
0065 class G4VoxelLimits;
0066 class G4VPhysicalVolume;
0067
0068 // Aliases
0069 using G4ProxyVector = std::vector<G4SmartVoxelProxy*>;
0070 using G4NodeVector = std::vector<G4SmartVoxelNode*>;
0071 using G4VolumeNosVector = std::vector<G4int>;
0072 using G4VolumeExtentVector = std::vector<G4double>;
0073
0074 /**
0075  * @brief G4SmartVoxelHeader represents a set of voxels, created by a single
0076  * axis of virtual division. It contains the individual voxels, which are
0077  * potentially further divided along different axes.
0078  */
0079
0080 class G4SmartVoxelHeader
0081 {
0082   public:
0083
0084     /**
0085      * Constructor for the topmost header, to begin voxel construction at a
0086      * given logical volume; 'pSlice' is used to set max and min equivalent
0087      * slice numbers for the header - they apply to the level of the header,
0088      * not its nodes.
0089      *  @param[in] pVolume Pointer to the logical volume to voxelise.
0090      *  @param[in] pSlice Max & min equivalent slice numbers for the header.
0091      */
0092     G4SmartVoxelHeader(G4LogicalVolume* pVolume, G4int pSlice = 0);
0093
0094     /**
0095      * Constructor for building and refine voxels between specified limits,
0096      * considering only the physical volumes numbered 'pCandidates'; 'pSlice'
0097      * is used to set max and min equivalent slice numbers for the header;
0098      * they apply to the level of the header, not its nodes.
0099      *  @param[in] pVolume Pointer to the logical volume to voxelise.
0100      *  @param[in] pLimits Refinement limits for building the voxels.
0101      *  @param[in] pCandidates Candidate volumes to be considered.
0102      *  @param[in] pSlice Max & min equivalent slice numbers for the header.
0103      */
0104     G4SmartVoxelHeader(G4LogicalVolume* pVolume,
0105                const G4VoxelLimits& pLimits,
0106                const G4VolumeNosVector* pCandidates,
0107                G4int pSlice = 0);
0108       //
0109
0110     /**
0111      * Destructor. Deletes all referenced nodes [but *not* the referenced
0112      * physical volumes].
0113      */
0114     ~G4SmartVoxelHeader();
0115
0116     /**
0117      * Equality operator.
0118      */
0119     G4bool operator == (const G4SmartVoxelHeader& pHead) const;
0120
0121     /**
0122      * Streaming operator.
0123      */
0124     friend std::ostream&
0125     operator << (std::ostream&s, const G4SmartVoxelHeader& h);
0126
0127     /**
0128      * Access functions for min/max equivalent slices (nodes & headers).
0129      */
0130     G4int GetMaxEquivalentSliceNo() const;
0131     void SetMaxEquivalentSliceNo(G4int pMax);
0132     G4int GetMinEquivalentSliceNo() const;
0133     void SetMinEquivalentSliceNo(G4int pMin);
0134
0135     /**
0136      * Returns the current division axis.
0137      */
0138     EAxis GetAxis() const;
0139
0140     /**
0141      * Returns the suggested division axis for parameterised volume.
0142      */
0143     EAxis GetParamAxis() const;
0144
0145     /**
0146      * Returns the maximum coordinate limit along the current axis.
0147      */
0148     G4double GetMaxExtent() const;
0149
0150     /**
0151      * Returns the minimum coordinate limit along the current axis.
0152      */
0153     G4double GetMinExtent() const;
0154
0155     /**
0156      * Returns the number of slices along the current axis.
0157      */
0158     std::size_t GetNoSlices() const;
0159
0160     /**
0161      * Returns the pointer to the proxy for the n-th slice
0162      * (numbering from 0, no bounds checking is performed).
0163      */
0164     G4SmartVoxelProxy* GetSlice(std::size_t n) const;
0165
0166     /**
0167      * Returns true if all slices are equal (after collection).
0168      */
0169     G4bool AllSlicesEqual() const;
0170
0171   private:  // 'Worker' / operation functions
0172
0173     /**
0174      * Builds and refine voxels for daughters of a specified volume 'pVolume'
0175      * which DOES NOT contain a REPLICATED daughter.
0176      */
0177     void BuildVoxels(G4LogicalVolume* pVolume);
0178
0179     /**
0180      * Builds voxels for a specified volume 'pVolume' containing a single
0181      * replicated volume.
0182      */
0183     void BuildReplicaVoxels(G4LogicalVolume* pVolume);
0184
0185     /**
0186      * Constructs nodes in simple consuming case.
0187      */
0188     void BuildConsumedNodes(G4int nReplicas);
0189
0190     /**
0191      * Builds and refines voxels between specified limits 'pLimits',
0192      * considering only the physical volumes 'pCandidates'. Main entry point
0193      * for "construction". Hardwired to stop at third level of refinement,
0194      * using the XYZ Cartesian axes in any order.
0195      */
0196     void BuildVoxelsWithinLimits(G4LogicalVolume* pVolume,
0197                                  G4VoxelLimits pLimits,
0198                          const G4VolumeNosVector* pCandidates);
0199
0200     /**
0201      * Calculates and stores the minimum and maximum equivalent neighbour
0202      * values for all slices.
0203      */
0204     void BuildEquivalentSliceNos();
0205
0206     /**
0207      * Collects the common nodes, deleting all but one to save memory
0208      * and adjusting stored slice pointers appropriately.
0209      */
0210     void CollectEquivalentNodes();
0211
0212     /**
0213      * Collects the common headers, deleting all but one to save memory
0214      * and adjusting stored slice pointers appropriately.
0215      */
0216     void CollectEquivalentHeaders();
0217
0218     /**
0219      * Builds the nodes corresponding to the specified axis 'pAxis', within
0220      * the specified limits 'pLimits', considering the daughters numbered
0221      * 'pCandidates' of the logical volume 'pVolume'.
0222      */
0223     G4ProxyVector* BuildNodes(G4LogicalVolume* pVolume,
0224                           G4VoxelLimits pLimits,
0225                           const G4VolumeNosVector* pCandidates,
0226                           EAxis pAxis);
0227
0228     /**
0229      * Calculates a "quality value" for the specified vector of voxels.
0230      * The value returned should be greater than zero and such that the
0231      * smaller the number the higher the quality of the slice; 'pSlice'
0232      * must consist of smart voxel node proxies only.
0233      */
0234     G4double CalculateQuality(G4ProxyVector* pSlice);
0235
0236     /**
0237      * Examined each contained node, refines (creates a replacement additional
0238      * dimension of voxels) when there is more than one voxel in the slice.
0239      */
0240     void RefineNodes(G4LogicalVolume* pVolume, G4VoxelLimits pLimits);
0241
0242   private:
0243
0244     /** Min and max equivalent slice nos for previous level. */
0245     G4int fminEquivalent;
0246     G4int fmaxEquivalent;
0247
0248     /** Axis for slices. */
0249     EAxis faxis, fparamAxis;
0250
0251     /** Max and min coordinate along faxis. */
0252     G4double fmaxExtent;
0253     G4double fminExtent;
0254
0255     /** Slices along axis. */
0256     G4ProxyVector fslices;
0257 };
0258
0259 #include "G4SmartVoxelHeader.icc"
0260
0261 #endif