Geant4의 UI Command 기초 이론

Geant4는 UI command라는 개념을 통해 C++ 언어로 하드코딩 하지 않고도 시뮬레이션 전반을 핸들링하거나 모니터링할 수 있도록 합니다. 이 글에서는 Geant4의 UI Command 사용에 대한 기초 이론을 다룹니다.

UI Command 개념

Geant4는 시뮬레이션 이전, 도중, 이후에 시뮬레이션의 조건 등을 조작하거나 정보를 추출하는 등의 다양한 기능을 수행할 수 있도록 UI Command라는 기능을 제공합니다.

UI Command는 Geant4에서 기본적으로 제공하는 built-in command와, 사용자가 직접 만들어 사용하는 messenger 기반 command로 구분할 수 있습니다. 둘 다 사용방법과 기본 이론은 동일합니다.

Built-in Command 일람

Built-in command 목록을 확인하는 방법을 소개합니다.

공식 홈페이지에서 제공하는 웹페이지
Qt 기반 GUI 형식으로 Geant4 어플리케이션을 실행한 뒤 왼쪽 부분의 Help 탭 확인

UI Command의 구성

기본 요소

UI Command는 다음의 세 가지로 구성됩니다.

Command directory
Command
Parameter(s)

실제 예시는 다음과 같습니다.

/run/verbose 1
/vis/viewer/flush

여기서 Parameter(s)가 여러 개 사용될 경우 각각을 구분하는 구분자는 공백입니다. 만약 공백이 있는 string을 파라미터로 사용해야 하는 경우에는, “"(double-quote)로 묶어줍니다.

Command 중에는 일부 parameter의 기본값이 존재해서 생략할 수 있는 경우도 있습니다. 만약 앞의 값을 생략하고 뒤의 값만 입력하려면, 생략할 값에 !를 적으면 됩니다. 예를 들어, 처음 값을 생략하여 기본값을 사용하고, 두번째 값만 직접 입력한다면 다음과 같이 적을 수 있습니다.

1/directory/command ! second

주석

각 줄마다, # 표시 이후는 주석처리됩니다.

예를 들면 다음과 같습니다.

1# This line will be commented
2/run/verbose 1
3/run/verbose 2 # After # mark will be commented.

UI Command의 입력

UI Command는 다음의 방법을 통해 입력 가능합니다.

C++ 코드 상에서 직접 입력
외부 파일을 통한 입력
프로그램 실행 후, (G)UI 명령줄을 통한 입력

C++ 코드 상에서 입력하기

G4UImanager라는 클래스가 관련 기능을 담당합니다.

이 클래스는 singleton 형태로 짜여있으며, GetUIpointer()라는 static 멤버함수를 통해 클래스 객체를 가져올 수 있습니다.

멤버함수 중 ApplyCommand() 함수를 활용하면 UI command를 실행할 수 있습니다.

이 함수의 원형은 G4int ApplyCommand(const G4String& aCommand)로, 문자열을 입력으로 받고, 실행 결과를 정수값으로 반환합니다.

사용 예시는 다음과 같습니다.

1G4UImanager::GetUIPointer()->ApplyCommand("/run/verbose 1");

ApplyCommand() 함수에 대한 상세 사항

ApplyCommand() 함수는 정상 실행 시 0을 반환하고, 오류가 있을 시 xyy형태의 양의 정수로 오류코드를 반환합니다. x는 G4UIcommandStatus.hh의 enum에 정의된 값이고, yy는 문제를 일으킨 첫 parameter의 번호입니다. 다음은 10.7 버전의 G4UIcommandStatus 클래스에서 발췌한 내용입니다.

 1enum G4UIcommandStatus
 2{
 3  fCommandSucceeded         = 0,
 4  fCommandNotFound          = 100,
 5  fIllegalApplicationState  = 200,
 6  fParameterOutOfRange      = 300,
 7  fParameterUnreadable      = 400,
 8  fParameterOutOfCandidates = 500,
 9  fAliasNotFound            = 600
10};

ApplyCommand() 함수로 UI command 실행을 시도하였다가 모종의 문제로 인해 실행을 실패하더라도, 프로그램은 아무런 알림 없이 그냥 진행됩니다. 필요하다면 코드 작성 시 반환되는 오류코드 값에 따라 대응하도록 직접 코딩해주시는 것이 좋습니다.

외부 파일을 통한 입력

대부분의 경우 UI command는 이 방법을 통해 입력됩니다.

이 방식을 이용하기 위해서는, 사용할 UI command를 ASCII 형태로 입력해 둔 파일이 필요합니다. 이 파일을 일반적으로 매크로파일이라고 부릅니다.

이 방법의 가장 큰 장점은 소스코드를 다시 컴파일하지 않고도 수정 가능하다는 점입니다.

특정 인자를 약간씩 바꿔가며 여러 번 시뮬레이션을 돌려야하는 등의 작업을 수행할 때, 컴파일을 한 번만 해서 실행파일을 생성한 뒤 매크로파일만 수정하며 손쉽게 여러 조건의 시뮬레이션을 돌릴 수 있게 됩니다.

사용을 위해서는 두 가지 준비가 필요합니다.

소스코드에서 매크로 파일을 사용하겠다는 선언 (UI command 중 /control/execute 매크로파일명 이용)
예를 들어, 일련의 UI command를 적어둔 파일 이름이 run.mac이라면 다음과 같이 입력
```
1G4UImanager::GetUIPointer()->ApplyCommand("/control/execute run.mac");
```

매크로파일 작성 (run.mac 파일의 예시)

1/run/verbose 1
2/tracking/verbose 1
3
4# empty line will be ignored.
5
6# You can also call another macro file here.
7/control/execute run2.mac
8
9/run/beamOn 100

매크로파일을 사용할 때의 주의사항은 다음과 같습니다.

매크로파일 내의 내용 중 실행할 수 없는 명령줄을 만나면, COMMAND NOT FOUND 경고문구가 발생하고 해당 매크로파일을 읽는 작업을 중단한 뒤 건너뜁니다.
매크로파일에 사용되는 명령어는 full-path로 작성해야 합니다. cd 등으로 경로이동을 시도하거나, 경로 정보 없이 command만 입력하면 오류가 발생합니다. 다음은 잘못된 사용 예입니다.
```
1cd /run/ # A macro file cannot contain "cd" command.
2verbose 1 # "verbose" does not contain its path.
```
매크로파일의 경로가 프로그램 실행파일의 경로와 다를 경우, 경로까지 입력해줘야 합니다. 예를 들어, 한 단계 상위 디렉토리(../)에 있는 run.mac 파일을 이용하려면 다음과 같이 입력합니다.
```
1G4UImanager::GetUIPointer()->ApplyCommand("/control/execute ../run.mac");
```