G4DataQuestionnaire =================== A quick survey to collect information about usage patterns of "Data Libraries"(*) in Geant4. Goal is to: 1. Ease setup and use by clients of Geant4 (currently require 1 environment variable per library), whilst supporting developers. 2. Identify and reduce any bottlenecks caused by reading of the many ASCII based files, in both single and multi threaded modes. (*) A directory containing 1-N file(s), possible organized hierarchically, that are read by code in Geant4 for the purposes of physics modelling. Currently known/used Data Libraries, plus listed purpose are: - G4NDL4.5, Neutron data files with thermal cross-sections - version 4.5 - G4EMLOW7.3, data files for low energy electromagnetic processes - version 7.3 - G4PhotonEvaporation5.2, data files for photon evaporation - version 5.2 - G4RadioactiveDecay5.2, data files for radioactive decay hadronic processes - version 5.2 - G4SAIDDATA1.1, data files from evaluated cross-sections in SAID data-base - version 1.1 - G4NEUTRONXS1.4, data files for evaluated neutron cross-sections on natural composition of elements - version 1.4 - G4ABLA3.1, data files for nuclear shell effects in INCL/ABLA hadronic mode - version 3.1 - G4PII1.3, data files for shell ionisation cross-sections - version 1.3 - G4ENSDFSTATE2.2, data files for nuclides properties - version 2.2 - G4RealSurface2.1.1, Optional data files for measured optical surface reflectance - version 2.1.1 - G4TENDL1.3.2, Optional data files for incident particles - version 1.3.2 Questions ========= If any question does not apply, just enter "N/A". 1. For the Geant4 categories your Working Group maintains, please list: i. The subcategories (if appropriate) and files/classes which access data libraries. ii. In these files/classes, how is the data accessed? a) directly via `getenv`? b) indirectly via C++ objects, if so which ones? iii. For each access use above, please list the Geant4 states in which data may be accessed, e.g. on Physics List creation, once per event, during tracking. iv. What method is used to parse the data? v. What C++ object(s) are used to hold the read/parsed data in memory? vi. Do you check or otherwise use the Data Library version? If so, give use cases (e.g new features added, file format/interface changes). = ------------------- 1.i ------------------ Regarding question 1.i, these are the subcategories and files/classes in Hadronic Physics that access the data libraries: - G4SAIDDATA* : it is accessed by: subcategory : hadronic/cross_sections/ class/file : G4ComponentSAIDTotalXS(.cc) Note: all reference physics lists need this data library. - G4NEUTRONXS* : it is accessed by: subcategory : hadronic/cross_sections/ classes/files : G4NeutronElasticXS(.cc) G4NeutronCaptureXS(.cc) G4NeutronInelasticXS(.cc) Note: all reference physics lists need this data library. - G4ABLA* : it is accessed by: subcategory : hadronic/models/abla/ class/file : G4AblaDataFile(.cc) Note: only if INCLXX is used (e.g. in FTFP_INCLXX physics list) and with the non-default option of using ABLA for the nuclear de-excitation, this data library is needed. - G4PhotonEvaporation* : it is accessed by: subcategory : hadronic/models/de_excitation/ class/file : G4LevelReader(.cc) Note: all reference physics lists need this data library. - G4RadioactiveDecay* : it is accessed by: subcategory : hadronic/models/radioactive_decay/ classes/files : G4RadioactiveDecayBase(.cc) G4RadioactiveDecay(.cc) Note: only if radioactive-decay is activated (e.g. by default in Shielding physics list) this data library is needed. - G4ENSDFSTATE* : it is accessed by: subcategory : particles/ class/file : G4NuclideTable(.cc) Note: all reference physics lists need this data library. - G4NDL* : it is accessed by: subcategory : hadronic/models/particle_hp/ classes/files : G4ParticleHPManager(.cc) G4ParticleHPNames(.cc) G4ParticleHPData(.cc) G4ParticleHPInelasticData(.cc) G4ParticleHPJENDLHEData(.cc) G4ParticleHPThermalScatteringData(.cc) G4ParticleHPThermalScattering(.cc) G4ParticleHPElastic(.cc) G4ParticleHPCapture(.cc) G4ParticleHPFission(.cc) G4ParticleHPInelastic(.cc) G4ParticleHPInelasticBaseFS(.cc) G4ParticleHPInelasticCompFS(.cc) G4ParticleHPElasticFS G4ParticleHPCaptureFS G4ParticleHPFFFissionFS G4ParticleHPFissionBaseFS G4ParticleHPFSFissionFS G4WendtFissionFragmentGenerator G4ENDFTapeRead Note: only for high-precision treatment of low-energy neutrons (as in all _HP physics lists), this data library is needed. - G4TENDL* : it is accessed by: subcategory : hadronic/models/particle_hp/ classes/files : G4ParticleHPManager(.cc) G4ParticleHPInelasticData(.cc) G4ParticleHPInelastic(.cc) G4ParticleHPIsoData(.cc) Note: only if high-precision treatment of low-energy charged particles - at least one of these: proton, deuteron, triton, 3He, alpha - (as in the physics list QGSP_BIC_AllHP), this data library is needed. ------------------- 1.ii ------------------ Regarding question 1.ii, in all cases in hadronic physics, the data libraries are accessed directly via `getenv` . ------------------- 1.iii ------------------ Regarding question 1.iii, these are the Geant4 states in which the data may be accessed, - G4SAIDDATA* : during tracking, at the first time the data is needed by an hadronic elastic or inelastic interaction. - G4NEUTRONXS* : during run-initialization, in particular by "BuildPhysicsTable". - G4ABLA* : during initialization (i.e. physics list creation). - G4PhotonEvaporation* : during tracking, at the first time the data is needed to de-excite or decay an unstable nucleus. - G4RadioactiveDecay* : during tracking, at the first time the data is needed to decay an unstable nucleus. - G4ENSDFSTATE* : during initialization (i.e. physics list creation). - G4NDL* : during run-initialization, in particular by "BuildPhysicsTable". - G4TENDL* : during run-initialization, in particular by "BuildPhysicsTable". ------------------- 1.iv ------------------ Regarding question 1.iv, these are the methods used to parse the data libraries: - G4SAIDDATA* : void G4ComponentSAIDTotalXS::ReadData( G4int , G4PhysicsVector* , const G4String& , const G4String& ); which calls the method: G4bool G4PhysicsVector::Retrieve( std::ifstream& , G4bool ); - G4NEUTRONXS* : void G4NeutronElasticXS::Initialise( G4int , G4DynamicParticle* , const char* ); G4PhysicsVector* G4NeutronCaptureXS::RetrieveVector( std::ostringstream& , G4bool ); G4PhysicsVector* G4NeutronInelasticXS::RetrieveVector( std::ostringstream& , G4bool ); all of which call the method: G4bool G4PhysicsVector::Retrieve( std::ifstream& , G4bool ); - G4ABLA* : bool G4AblaDataFile::readData(); - G4PhotonEvaporation* : const G4LevelManager* G4LevelReader::LevelManager( G4int , G4int , G4int , std::ifstream& ); which calls the methods: G4bool G4LevelReader::ReadDataItem(std::istream& , G4double& ); G4bool G4LevelReader::ReadDataItem(std::istream& , G4float& ); G4bool G4LevelReader::ReadDataItem(std::istream& , G4int& ); G4bool G4LevelReader::ReadDataItem(std::istream& , G4String& ); - G4RadioactiveDecay* : G4DecayTable* G4RadioactiveDecayBase::LoadDecayTable( const G4ParticleDefinition& ); G4DecayTable* G4RadioactiveDecay::LoadDecayTable( const G4ParticleDefinition& ); - G4ENSDFSTATE* : void G4NuclideTable::GenerateNuclide(); - G4NDL* : void G4ParticleHPManager::GetDataStream( G4String , std::istringstream& ); G4PhysicsVector* G4ParticleHPJENDLHEData::readAFile( std::fstream* ); E_P_E_isoAng* G4ParticleHPThermalScattering::readAnE_P_E_isoAng( std::istream* ); - G4TENDL* : void G4ParticleHPManager::GetDataStream( G4String , std::istringstream& ); ------------------- 1.v ------------------ Regarding question 1.v, the following C++ objects are used to hold the read/parsed data in memory: - G4SAIDDATA* : objects of type G4LPhysicsFreeVector . - G4NEUTRONXS* : objects of type G4PhysicsLogVector . - G4ABLA* : C-arrays defined in the class G4AblaVirtualData . - G4PhotonEvaporation* : objects of type G4LevelManager . - G4RadioactiveDecay* : objects of type G4DecayTable . - G4ENSDFSTATE* : two std maps defined in the class G4NuclideTable . - G4NDL* : objects of type std::istringstream , which are then further parsed and stored as objects of type G4LPhysicsFreeVector and std maps. - G4TENDL* : objects of type std::istringstream , which are then further parsed and stored as objects of type G4LPhysicsFreeVector and std maps. ------------------- 1.vi ------------------ Regarding question 1.vi , there is no check of the data library version, so if there is an inconsistency between the Geant4 version and the data library version (e.g. older data library with a newer Geant4 version, or, vice versa, an older Geant4 version with a newer data library) the behaviour is undefined, i.e. an application can crash or run silently but producing eventually wrong results. ----------------------------------------------------------------------------- 2. Please list any Data Libraries your Working Group maintains/develops/contributes to. For each library in this list, please provide i. How data is added/edited/removed? ii. Under what circumstances are the Major, Minor and Patch elements of the version number changed? = The Hadronic Physics Working Group is responsible of the following Data Libraries ("*" below means the version number of the library, which can have 2 or 3 digits, like "1.2" or "1.2.3"): - G4SAIDDATA* - G4NEUTRONXS* - G4ABLA* - G4PhotonEvaporation* - G4RadioactiveDecay* - G4ENSDFSTATE* - G4NDL* - G4TENDL* Note: in the coming December release, G4 10.5, there will be a new Data Library "G4INCL*" used only by INCLXX. All the answers included here are not considering this library, because the corresponding code has not yet been committed in the Geant4 SVN repository. ------------------- 2.i ------------------ Regarding the question 2.i, for each of these Data Libraries: new information is added when it is available, and the Geant4 developers who are in charged of these data libraries have the time to work on them, in particular to validate the new information and checking that previous results are fine. This work requires a major effort, that is why there can be sometimes a significant delay before the new information is available to Geant4 users. ------------------- 2.ii ------------------ Regarding the question 2.ii, for each of these Data Libraries: - the Major number of a data library is changed when it is not backward-compatible, i.e. previous versions of Geant4 cannot handle it - for instance because the format has changed, or some old, deprecated information has been deleted; - the Minor number of a data library is changed when new data has been added, but it is backward-compatible, i.e. older versions of Geant4 are still able to use it (regardless whether they are able or not to use the new, added data); - the Patch number of a data library is changed (rather rarely), when at the moment of creating a Geant4 patch release, one or more bug-fixes have been done (with respect the the data library used in the previous Geant4 patch) on the data library to correct wrong information.