Geant4에서 기본 제공하는 G4ParticleGun 클래스보다 좀 더 많은 기능이 필요해서 제가 직접 만들어 쓰고 있는 AdvancedParticleGun 클래스를 소개합니다. 특정 지오메트리를 선원항으로 사용하려는 경우, 특정 지오메트리 방향으로만 방사선을 방출시키고자 하는 경우, 방사성동위원소를 선원으로 설정하려는 경우에 유용하게 사용할 수 있습니다.

TL;DR

용도

• 이미 모사해 둔 지오메트리 중 하나를 선원항으로 지정하고 싶을 때
• 방사선이 방출되는 방향을 특정 지오메트리 쪽으로 제한하고 싶을 때
• 방사성동위원소가 방출하는 감마선 및 엑스선만을 선원항으로 두고 싶을 때

다운로드 경로

• 필요한 항목만 압축한 파일: https://evandde.github.io/uploads/advpg.zip
• 예제가 담긴 GitHub repository: evandde/example_advpg: Example of Advanced Particle Gun class for Geant4. (github.com)
• 예제 압축파일 다운 링크(GitHub repository에서 받는 것과 동일): example_advpg.zip

사용방법

• 위에서 advpg.zip을 다운받아, 압축을 풀어서 나오는 3개 폴더(ICRP07DATA, include, src)를 프로젝트에 붙여넣기 (Geant4의 일반적인 디렉토리 구성을 따른다고 가정)
• 사용자의 PrimaryGeneratorAction에서, ParticleGun 대신 AdvancedParticleGun 객체를 만들어서 사용
• 기존 ParticleGun의 기능은 그대로 사용 가능
• 추가적으로 다음의 멤버함수를 사용 가능
  • void SetNuclideSource(G4String nuclideName)
  • void SetMinPhotonEnergy(G4double minPhotonEnergy)
  • void SetSourceVolume(G4String sourceVolName)
  • void SetTargetVolume(G4String targetVolName, G4double margin)
• 기능에 따라 초기 입자의 가중치(weight)가 조절될 수 있음

설치방법

여러분의 Geant4 프로젝트는 다음과 같은 일반적인 디렉토리 구성을 따른다고 가정하여 진행합니다.

projectDirectory
|- main.cc
|- include/
|  |- .hh
|  |- ...
|- src/
|  |- .cc
|  |- ...
|- CMakeLists.txt
|- .mac
|- ...

일단, advpg.zip 파일을 다운로드 받습니다. 제공해드리는 advpg.zip 압축파일에는 다음과 같은 내용물이 들어 있습니다.

ICRP07DATA/
|- ICRP-07.NDX	# ICRP107 제공; Index File
|- ICRP-07.RAD	# ICRP107 제공; Radiation File
include/
|- AdvancedParticleGun.hh
|- ICRP07Manager.hh
src/
|- AdvancedParticleGun.cc
|- ICRP07Manager.cc

이를 그대로 여러분의 프로젝트에 옮겨 넣으시면, ICRP07DATA라는 디렉토리가 추가로 생기고, include와 src 디렉토리는 기존의 것과 합쳐져 AdvancedParticleGun과 ICRP07Manager클래스에 관한 두 개씩의 파일만 추가될 것입니다.

최종적으로 여러분의 프로젝트가 다음과 같이 되어있으면 세팅은 끝입니다.

projectDirectory
|- main.cc
|- ICRP07DATA/
|  |- ICRP-07.NDX
|  |- ICRP-07.RAD
|- include/
|  |- AdvancedParticleGun.hh
|  |- ICRP07Manager.hh
|  |- ...
|- src/
|  |- AdvancedParticleGun.cc
|  |- ICRP07Manager.cc
|  |- ...
|- CMakeLists.txt
|- .mac
|- ...

클래스 설명

AdvancedParticleGun 클래스

AdvancedParticleGun 클래스는 Geant4에서 공식으로 제공하는 G4ParticleGun 클래스를 public으로 상속받아 만들어진 클래스입니다. 따라서 여러분이 기존에 G4ParticleGun 클래스를 사용하던 방식과 동일하게 AdvancedParticleGun 클래스를 사용하시면 됩니다. 여러분이 G4VUserPrimaryGeneratorAction 클래스를 상속받아 만든 클래스 내에서 AdvancedParticleGun 클래스의 객체를 만들고, 기존과 동일한 방법으로 GeneratePrimaryVertex() 멤버함수를 이용하여 초기 입자를 생성할 수 있습니다.

G4ParticleGun 클래스가 제공하는 다음과 같은 멤버함수도 동일하게 사용 가능합니다.

• SetParticleDefinition()
• SetParticleCharge()
• SetParticleEnergy()
• SetParticleMomentumDirection()
• ...

이와 더불어, AdvancedParticleGun 클래스는 추가적으로 다음과 같은 멤버함수를 제공합니다.

• SetSourceVolume()
• GetSourceVolume()
• SetTargetVolume()
• GetTargetVolume()
• SetTargetVolumeMargin()
• GetTargetVolumeMargin()
• SetNuclideSource()
• GetNuclideSource()
• SetMinPhotonEnergy()
• GetMinPhotonEnergy()

ICRP07Manager 클래스

ICRP07Manager 클래스는 ICRP07DATA 디렉토리 내에 존재하는 ICRP Publication 107의 데이터를 읽어오고 활용하기 위한 클래스입니다.

사용자가 ICRP07Manager 클래스를 직접 핸들링할 필요는 없으며, ICRP07Manager 클래스의 기능 중 사용자가 필요한 기능은 AdvancedParticleGun 클래스를 통해 사용할 수 있도록 포장(wrapping)해 두었습니다.

사용방법 상세

지오메트리를 선원항으로 설정

사용자가 만들어 둔 G4VPhysicalVolume 클래스의 객체 중 하나를 균일하게 방사선을 방출하는 선원항으로 설정합니다. 이 기능을 사용하면 다음 그림과 같이 특정 지오메트리를 선원항으로 사용할 수 있습니다.

AdvancedParticleGun 클래스의 멤버함수인 SetSourceVolume() 함수를 사용합니다. 원형은 다음과 같습니다.

void SetSourceVolume(G4VPhysicalVolume *sourceVol);
void SetSourceVolume(G4String sourceVolName);

사용자는 SetSourceVolume() 함수의 입력인자로 G4VPhysicalVolume 클래스 객체의 포인터를 직접 입력할 수 있습니다.

혹은, 해당 객체의 이름(Geant4 내에서 명명된 G4String형 이름)이 유일하다면, 포인터 대신 이름만 입력할 수도 있습니다. 이 경우에는 G4PhysicalVolumeStore 클래스를 활용하여, 해당 이름을 갖는 G4VPhysicalVolume 클래스의 객체를 자동으로 찾아옵니다.

❌ 주의사항
G4PhysicalVolumeStore 클래스의 특성 상, 이름이 중복되는 경우에는 그 중 먼저 검색된 하나의 객체만을 반환합니다. 이 경우, 의도와 달리 동작할 수 있습니다.

선원항으로 사용할 G4VPhysicalVolume 클래스 객체가 선택되면, 앞으로 AdvancedParticleGun 클래스는 선원의 위치를 해당 선원 객체 내부의 임의의 지점으로 균일하게 샘플링합니다. 샘플링 방식은 해당 지오메트리를 감싸는 직육면체를 상정하여 샘플링한 뒤, rejection method 기법을 활용합니다. 따라서, 지오메트리의 형태에 따라 선원의 위치를 샘플링하는 데에 소요되는 시간이 상이할 수 있습니다.

만약 해당 기능을 해제하여 사용하지 않고자 하는 경우에는, SetSourceVolume() 함수의 입력인자로 nullptr을 넣어주시면 됩니다.

이 기능은 선원의 위치를 지정하므로, SetParticlePosition() 함수와 기능상 충돌합니다. 만약 SetSourceVolume() 함수를 통해 유효한 G4VPhysicalVolume 객체로 선원항이 설정된 상태라면, SetParticlePosition() 함수를 무시하고 이 함수로 설정된 지오메트리를 우선합니다. 이를 원치 않는다면 반드시 SetSourceVolume() 함수의 기능을 해제하셔야 합니다.

AdvancedParticleGun 클래스의 멤버함수인 GetSourceVolume() 함수를 사용하면, 현재 설정된 선원 지오메트리의 G4VPhysicalVolume 클래스 객체의 포인터를 확인할 수 있습니다. 이 함수의 원형은 다음과 같습니다.

G4VPhysicalVolume *GetSourceVolume() const;

지오메트리를 타겟으로 설정

사용자가 만들어 둔 G4VPhysicalVolume 클래스의 객체 중 하나를 방사선이 도달할 타겟으로 설정합니다. 이 기능을 사용하면 다음 그림과 같이 특정 지오메트리를 타겟으로 사용할 수 있습니다.

AdvancedParticleGun 클래스의 멤버함수인 SetTargetVolume() 함수를 사용합니다. 원형은 다음과 같습니다.

void SetTargetVolume(G4VPhysicalVolume *targetVol, G4double margin = 0.);
void SetTargetVolume(G4String targetVolName, G4double margin = 0.);

사용자는 SetTargetVolume() 함수의 입력인자로 G4VPhysicalVolume 클래스 객체의 포인터를 직접 입력할 수 있습니다.

혹은, 해당 객체의 이름(Geant4 내에서 명명된 G4String형 이름)이 유일하다면, 포인터 대신 이름만 입력할 수도 있습니다. 이 경우에는 G4PhysicalVolumeStore 클래스를 활용하여, 해당 이름을 갖는 G4VPhysicalVolume 클래스의 객체를 자동으로 찾아옵니다.

❌ 주의사항
G4PhysicalVolumeStore 클래스의 특성 상, 이름이 중복되는 경우에는 그 중 먼저 검색된 하나의 객체만을 반환합니다. 이 경우, 의도와 달리 동작할 수 있습니다.

타겟으로 사용할 G4VPhysicalVolume 클래스 객체가 선택되면, 앞으로 AdvancedParticleGun 클래스는 현재 선원의 위치로부터 해당 타겟 객체를 완전히 감싸는 원뿔 내부의 임의의 방향으로 균일하게 샘플링합니다. 샘플링 방식은 한 지점으로부터 isotropic한 방향을 샘플링하되 공간각을 원뿔 내부로 제한하는 방식을 사용합니다.

추가적으로 SetTargetVolume() 함수는 두 번째 인자로 길이 형태(G4double 자료형)의 margin 값을 입력받습니다. 이는 타겟 G4VPhysicalVolume 객체를 딱 맞게 감싸는 원뿔을 기준으로, 이보다 좀 더 여유를 두어 공간각이 큰 원뿔로 방향을 설정하고자 할 때 사용합니다. 사용자는 margin값을 별도로 입력하지 않아도 되며, 이 경우 기본값은 0이 되어 타겟 G4VPhysicalVolume 객체를 딱 맞게 감싸는 원뿔로 방향이 설정됩니다.

만약 margin 값만 바꾸고 싶은 경우에는, SetTargetVolumeMargin() 멤버함수를 사용할 수도 있습니다. 이 함수의 원형은 다음과 같습니다.

void SetTargetVolumeMargin(G4double margin);

만약 해당 기능을 해제하여 사용하지 않고자 하는 경우에는, SetTargetVolume() 함수의 입력인자로 nullptr을 넣어주시면 됩니다.

이 기능은 선원의 방향을 지정하므로, SetParticleMomentumDirection() 함수와 기능상 충돌합니다. 만약 SetTargetVolume() 함수를 통해 유효한 G4VPhysicalVolume 객체로 선원항이 설정된 상태라면, SetParticleMomentumDirection() 함수를 무시하고 이 함수로 설정된 지오메트리를 우선합니다. 이를 원치 않는다면 반드시 SetTargetVolume() 함수의 기능을 해제하셔야 합니다.

AdvancedParticleGun 클래스의 멤버함수인 GetTargetVolume() 함수를 사용하면, 현재 설정된 타겟 지오메트리의 G4VPhysicalVolume 클래스 객체의 포인터를 확인할 수 있습니다. 이 함수의 원형은 다음과 같습니다.

G4VPhysicalVolume *GetTargetVolume() const;

더불어, GetTargetVolumeMargin() 함수를 사용하면, 현재 설정된 margin 값을 확인할 수 있습니다. 이 함수의 원형은 다음과 같습니다.

G4double GetTargetVolumeMargin() const;

가중치 변화

SetTargetVolume() 함수의 주요한 특징 중 하나는 초기입자의 가중치(weight)를 변화시킨다는 것입니다.

전 방향($\Omega=4\pi$

SetTargetVolume() 함수는 이 작업을 자동으로 수행합니다.

SetTargetVolume() 함수를 통해 결정된 원뿔의 공간각을 $\Omega$라 할 때, 초기입자의 가중치는 $\frac{\Omega}{4\pi}$

이렇게 변화된 가중치는 G4Track 클래스의 멤버함수인 GetWeight() 함수 등을 통해 확인할 수 있습니다.

방사성동위원소를 선원항으로 설정

선원항의 초기입자를 특정 방사성동위원소가 붕괴되며 방출하는 감마선 및 엑스선으로 설정합니다. 방사성동위원소의 핵종을 결정하면, 그 핵종이 붕괴하며 방출하는 감마선과 엑스선의 방출률(yield)을 반영하여 자동으로 초기입자가 샘플링됩니다. 붕괴된 딸핵종이 불안정한 핵종인 경우에는 딸핵종이 붕괴하며 방출하는 감마선과 엑스선도 붕괴확률 및 방출률을 반영하여 초기입자 군에 포함됩니다. 이때 붕괴도식, 붕괴확률, 방출률 등의 정보는 ICRP Publication 107의 정보를 따릅니다.

AdvancedParticleGun 클래스의 멤버함수인 SetNuclideSource() 함수를 사용합니다. 원형은 다음과 같습니다.

void SetNuclideSource(G4String nuclideName);

사용자는 SetNuclideSource() 함수의 입력인자로 G4String 형 데이터인 핵종명(nuclideName)을 입력할 수 있습니다. 이 때 핵종명은 "Cs-137", "Co-60" 등과 같이, "{원소기호}-{질량수}"의 형태로 입력해야 합니다.

ICRP Publication 107에서 제공하는 데이터가 존재하는 유효한 방사성동위원소가 선택된 경우, 앞으로 AdvancedParticleGun 클래스는 초기입자를 광자(G4Gamma)로 고정하고, 매 초기입자를 발생시킬 때마다 광자의 에너지를 붕괴도식, 붕괴확률, 방출률에 따라 샘플링합니다.

❌ 주의사항
이 기능은 모든 붕괴도식에 대해 단순히 각 딸핵종으로의 붕괴 확률만 고려합니다.
반감기, 모핵종/딸핵종 간의 방사능 비율, 시간에 따른 방사능 변화 등은 반영하지 않습니다.
따라서, 영년평형(secular equilibrium)을 이루지 않는 핵종의 경우에는 의도하지 않은 결과가 도출될 수 있음에 주의하시기 바랍니다.

만약 해당 기능을 해제하여 사용하지 않고자 하는 경우에는, SetNuclideSource() 함수의 입력인자로 빈 스트링("")을 넣어주시면 됩니다.

이 기능은 선원의 입자와 에너지를 지정하므로, SetParticleDefinition() 함수 및 SetParticleEnergy() 함수와 기능상 충돌합니다. 만약 SetNuclideSource() 함수를 통해 유효한 방사성동위원소로 선원항이 설정된 상태라면, SetParticleDefinition() 함수와 SetParticleEnergy() 함수를 무시하고 이 함수로 설정된 선원항 정보를 우선합니다. 이를 원치 않는다면 반드시 SetNuclideSource() 함수의 기능을 해제하셔야 합니다.

AdvancedParticleGun 클래스의 멤버함수인 GetNuclideSource() 함수를 사용하면, 현재 설정된 방사성동위원소의 핵종명을 확인할 수 있습니다. 이 함수의 원형은 다음과 같습니다.

G4String GetNuclideSource() const;

에너지 하한선 설정

추가적으로, 사용자가 저에너지 엑스선의 방출을 원하지 않는 경우에는 AdvancedParticleGun 클래스의 멤버함수인 SetMinPhotonEnergy() 함수를 통해, 발생하게 될 감마선과 엑스선의 에너지 하한선을 설정할 수 있습니다. 이 함수의 원형은 다음과 같습니다.

void SetMinPhotonEnergy(G4double minPhotonEnergy);

만약 별도로 이를 설정하지 않은 경우에는 에너지 하한선(minPhotonEnergy)이 0으로 설정된 것으로 간주하며, ICRP Publication 107 데이터에 제시된 모든 감마선과 엑스선이 선원항으로 설정됩니다.

AdvancedParticleGun 클래스의 멤버함수인 GetMinPhotonEnergy() 함수를 사용하면, 현재 설정된 에너지 하한선의 값을 확인할 수 있습니다. 이 함수의 원형은 다음과 같습니다.

G4double GetMinPhotonEnergy() const;

가중치 변화

SetNuclideSource() 함수의 주요한 특징 중 하나는 초기입자의 가중치(weight)를 변화시킨다는 것입니다.

방사성동위원소의 핵이 한 번 붕괴하는 것을 하나의 초기입자로 보았을 때, 이 함수가 제공하는 기능은 붕괴를 통해 발생되는 감마선(혹은 엑스선) 자체를 하나의 초기입자로 설정한다는 편향(bias)이 발생합니다.

예를 들어, Co-60과 같이 1회의 붕괴로 1.173 MeV의 감마선과 1.332 MeV의 감마선이 각각 1.0의 Yield로 발생하는 경우를 생각해봅시다(계산의 편의를 위해 Yield값을 근사적으로 이용하였으며 엑스선의 방출률을 무시했습니다). Co-60 핵 하나가 붕괴하였다면 하나의 초기입자로부터 감마선의 Yield의 총 합인 2.0개 만큼의 감마선이 나와야 합니다. 그러나 AdvancedParticleGun 클래스의 SetNuclideSource() 함수를 사용하면, 1.173 MeV의 감마선과 1.332 MeV의 감마선 중 한 개만 살아남아 초기입자가 될 것입니다. 따라서, 하나의 감마선이 Yield의 총 합인 2.0만큼의 가중치(weight)를 가지고 수송이 이루어져야 합니다.

SetNuclideSource() 함수는 이에 따른 가중치 변화를 자동으로 수행합니다.

SetNuclideSource() 함수를 통해 발생되는 초기입자는, 설정된 방사성동위원소가 방출하는 모든 감마선과 엑스선의 방출률(Yield)의 총 합만큼 곱해진 가중치를 가지게 됩니다. 위에서 예로 들은 Co-60라면, 각 감마선은 원래 가중치의 두 배로 설정되는 것입니다.

만약, 사용자가 SetMinPhotonEnergy() 함수를 통해 에너지 하한선을 설정하였다면, 이로 인해 배제되는 감마선과 엑스선의 방출률은 제외하고 총 합을 구하게 됩니다.

이렇게 변화된 가중치는 G4Track 클래스의 멤버함수인 GetWeight() 함수 등을 통해 확인할 수 있습니다.

License

Copyright (C) 2021, Evan Kim ([email protected])

All files except ICRP07DATA directory and its inside are licensed under a Creative Commons license: https://creativecommons.org/licenses/by-nc-sa/4.0/

The files in ICRP07DATA directory is from ICRP 107 copyright 2008 Eckerman and Endo. This data is provided with the following text in the license.txt file:

ICRP-07 Data Files Copyright Notice

Copyright (C) 2008 A. Endo and K.F. Eckerman, Authors. All Rights Reserved.

Permission is hereby granted to any person obtaining a copies of the ICRP-07 data files and associated documentation to use, copy, and distribute these materials and the documentation for educational, research, and not-for-profit purposes, without fee and without a signed licensing agreement provided that the file LICENSE.TXT containing the above copyright notice, this paragraph and the following two paragraphs appears in all copies, modifications, and distributions.

IN NO EVENT SHALL THE AUTHORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THE SOFTWARE, ITS DATA FILES, AND THE DOCUMENTATION.

THE AUTHORS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE, DATA FILES AND ACCOMPANYING DOCUMENTATION PROVIDED HEREUNDER IS PROVIDED "AS IS". THE AUTHORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, FUTURE UPDATES, ENHANCEMENTS, OR MODIFICATIONS TO THE SOFTWARE.