10. How to Build PHITS¶
If user-defined sources (usrsors.f) or [t-userdefined] are used, PHITS must be compiled.
A Fortran compiler is therefore required.
PHITS has been tested with Intel oneAPI and gfortran.
In particular, the use of Intel oneAPI is recommended on platforms other than macOS.
Please note that issues arising from the use of other compilers may not be fully supported.
PHITS can be compiled in a standard environment; however, some extended features require additional libraries. For example, parallel computation can be achieved using OpenMP or MPI, enabling faster execution for large-scale simulations. OpenMP is available as a compiler feature, whereas MPI requires a separate MPI library. In addition, by using the HDF5 library, it is possible to read tetrahedral mesh geometries in HDF5 format and to output tally results in HDF5 format (ph5out). These libraries are optional, and the corresponding features are enabled only when they are available.
Table 10.1 summarizes the combinations of compilers and configurations for each OS. Here, single denotes execution without parallelization, MPI and OpenMP denote parallel execution using the MPI protocol and OpenMP, respectively, and hybrid denotes a configuration combining both methods. For details on parallel computation, see Section 11.
OS |
Intel oneAPI |
Intel oneAPI |
Intel oneAPI |
Intel oneAPI |
gfortran |
gfortran |
gfortran |
gfortran |
|---|---|---|---|---|---|---|---|---|
single |
MPI |
Open MP |
hybrid |
single |
MPI |
Open MP |
hybrid |
|
Windows |
yes |
yes |
yes |
yes |
yes |
yes [1] |
||
Mac |
yes |
yes [1] |
||||||
Linux |
yes |
yes |
yes |
yes |
yes |
yes [1] |
10.1. Build Procedure on Windows OS¶
10.1.1. Installation of Compilers and Libraries¶
On Windows, Intel oneAPI ifx is recommended as the standard compiler.
In addition, Visual Studio should be installed to provide the libraries and tools required for building.
For installation instructions, refer to phits/document/Install-IntelFortran-OneAPI-en.pdf.
If CMake [2] and ninja [3] are not included in your Visual Studio installation, please download and install them separately from their respective websites.
Although not required in most cases, if you intend to use the HDF5 library [4], it should also be installed separately. However, since some issues occur in version 2.0.0 and later, please use version 1.14.6 [5].
10.1.2. Building PHITS¶
10.1.2.1. Build Method Using CMake¶
Launch the Intel oneAPI Command Prompt for Intel 64 for Visual Studio 2022 and use it as the terminal.
To open it, open the Windows search box, type oneAPI, and press Enter.
Then, change the current directory in the terminal window.
cd C:\phits\src
Since the PHITS Fortran source files and the CMake-related files are located in C:\phits\src, move to this directory.
The build is basically performed by executing the CMake command twice. The required options differ depending on whether you run without parallelization (single) or with parallelization (OpenMP or MPI).
The main options are listed below.
For other options, refer to cmake --help.
Option |
Description |
|---|---|
-S |
Specifies the folder containing |
-B |
Specifies the build folder. It can be set arbitrarily and will be created automatically if it does not exist. |
-G |
Specifies the generator (a list of available generators can be obtained with |
-DCMAKE_BUILD_TYPE:STRING |
Sets the build type (Release or Debug). When Debug is specified, PHITS is built in debug mode, producing |
-DCMAKE_RUNTIME_OUTPUT_DIRECTORY |
Specifies the output directory for the executable files. |
-DPHITS_ADD_SUFFIX |
Specifies whether to append the suffix |
-DPHITS_USE_OMP |
Specifies whether to enable parallel computation using OpenMP (=yes to enable OpenMP, =no to disable parallelization). |
-DPHITS_USE_MPI |
Specifies whether to enable parallel computation using MPI (=yes to enable MPI, =no to disable parallelization). |
-DPHITS_USE_HDF5 |
Specifies whether to use the HDF5 library (=yes to use, =no not to use). |
-DCMAKE_Fortran_COMPILER |
Specifies the Fortran compiler to be used. |
-T |
Specifies the toolset. When using the Visual Studio generator, specify |
10.1.2.1.1. Single Mode¶
The following describes how to compile PHITS in single mode (without parallelization).
You can build the PHITS executable by running the following two CMake commands.
After executing them, the executable files phits_win.exe (and angel_win.exe) will be generated in the \phits\bin\recompiled folder.
cmake -S . -B build_single -G Ninja -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=./../../bin/recompiled -DPHITS_ADD_SUFFIX=yes
cmake --build build_single
10.1.2.1.2. Single Mode (Option 1)¶
By using Ninja’s Multi-Config mode, both Release and Debug configurations can be handled within a single build folder. The following command creates such a build.
cmake -S . -B build_multi -G "Ninja Multi-Config" -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=./../../bin/recompiled -DPHITS_ADD_SUFFIX=1
Here, the build_multi folder is used to store the multi-configuration build files.
Then, you can select either Release or Debug using the --config option as follows:
cmake --build build_multi --config Release
or
cmake --build build_multi --config Debug
Note that a new folder named Release or Debug will be created inside the output directory, and the corresponding executable file will be placed in that folder.
10.1.2.1.3. Single Mode (Option 2)¶
When using Visual Studio as the generator, run the following CMake command:
cmake -S . -B build_vs -G "Visual Studio 17 2022" -T "fortran=ifx" -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=../../bin/recompiled -DPHITS_ADD_SUFFIX=1
Here, the build_vs folder is used to store the build files.
Since this generator is also multi-config, you must specify either Release or Debug when running CMake with the --build option, just as with Ninja Multi-Config.
10.1.2.1.4. Single Mode (Option 3)¶
To build PHITS with HDF5 enabled, add the -DPHITS_USE_HDF5=yes option to the cmake command as follows:
cmake -S . -B build_hdf5 -G Ninja -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=./../../bin/recompiled -DPHITS_ADD_SUFFIX=yes -DPHITS_USE_HDF5=yes
cmake --build build_hdf5
10.1.2.1.5. Single Mode (Option 4)¶
You can also use gfortran as the Fortran compiler by specifying it with the -DCMAKE_Fortran_COMPILER option.
cmake -S . -B build_gfortran -G Ninja -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=./../../bin/recompiled -DPHITS_ADD_SUFFIX=yes -DCMAKE_Fortran_COMPILER=gfortran
cmake --build build_gfortran
If only gfortran is installed, you can build PHITS without specifying this option. If both ifx and gfortran are installed, you can select the compiler using this option.
10.1.2.1.6. OpenMP Mode¶
You can build PHITS with the following option.
The executable file phits_openmp_win.exe will be generated.
cmake -S . -B build_openmp -G Ninja -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=./../../bin/recompiled -DPHITS_ADD_SUFFIX=yes -DPHITS_USE_OMP=yes
cmake --build build_openmp
10.1.2.1.7. MPI Mode¶
You can build PHITS with the following option.
The executable file phits_mpi_win.exe will be generated.
cmake -S . -B build_mpi -G Ninja -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=./../../bin/recompiled -DPHITS_ADD_SUFFIX=yes -DPHITS_USE_MPI=yes
cmake --build build_mpi
10.1.2.2. Build Method Using Microsoft Visual Studio¶
The /phits/bin/ folder contains a solution file phits-intel.sln that can be used in an environment combining Microsoft Visual Studio and Intel Fortran.
For installation instructions of these software packages, refer to phits/document/Install-IntelFortran-OneAPI-en.pdf.
This build procedure is the same as the compilation method using phits-intel.vfproj in versions earlier than 3.34.
If the build is successful, the executable file will be generated in the /phits/bin/ folder.
10.1.2.3. Executable Replacement¶
When PHITS is built using CMake or Microsoft Visual Studio, the executable files are generated in either the \phits\bin\recompiled or \phits\bin directory, respectively.
After confirming that the new executable files have been created in each directory, open phits.bat using a text editor such as PHITS-Pad and modify it as follows:
@echo off
title PHITS: %1
set PHITS_Single_EXE="%PHITSPATH%/bin/recompiled/phits_win.exe"
set PHITS_MPI_EXE="%PHITSPATH%/bin/phits_mpi_win.exe"
set PHITS_OpenMP_EXE="%PHITSPATH%/bin/phits_openmp_win.exe"
set PHITS_Debug_EXE="%PHITSPATH%/bin/phits_win_dbg.exe"
Here, the file specified after PHITS_Single_EXE= is changed to recompiled/phits_win.exe, which is generated using CMake.
After saving this modification, the newly built executable will be used in the standard execution via the Send to operation.
10.2. macOS¶
10.2.1. Introduction¶
To build PHITS yourself, you must first install the compiler and required libraries, then proceed to the PHITS build process.
10.2.2. Installing Compilers and Compilation Tools¶
On macOS, gfortran is used as the Fortran compiler. You can install gfortran using either Homebrew or MacPorts. This section describes the method using Homebrew. If you prefer MacPorts, please refer to its official documentation.
If Homebrew is not installed, execute the following command in your terminal to install it:
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Next, install the Fortran compiler along with cmake and ninja, which are used for the compilation process.
$ brew install gcc cmake ninja
10.2.3. Installing Libraries¶
OpenMPI is required for parallel computing via MPI and can be installed using Homebrew.
$ brew install open-mpi
HDF5 is required to read and write files in HDF5 format and can be installed via Homebrew. Operation has been verified with HDF5 version 1.14.6.
$ brew tap-new local/tools
$ brew extract --version=1.14.6 --git-revision=b2665fee6a29d19164cbc3ed569792f43d3b178e hdf5 local/tools
$ brew install local/tools/hdf5@1.14.6
10.2.4. Building PHITS¶
It is assumed that the PHITS source code resides in the src directory and the build directory
is used for the build process, both located at the same directory level.
Create a build directory and move into it.
$ mkdir ${PHITSPATH}/build
$ cd ${PHITSPATH}/build
Build Configuration
To build for a single core as an example, execute the following command:
$ cmake -G "Ninja Multi-Config" -S ../src -B .
You can enable parallelization with OpenMP or MPI, or enable HDF5 support by adding specific options or variables to the command above. Multiple options can be specified simultaneously.
Feature |
Option or Variable |
|---|---|
Parallelization via OpenMP |
|
Parallelization via MPI |
|
Enable HDF5 |
|
To enable HDF5, use the following:
$ cmake -G "Ninja Multi-Config" -S ../src -B . \
-DPHITS_USE_HDF5:BOOL=ON \
-DHDF5_ROOT:PATH=$HOME/local/hdf5
To use HDF5 and OpenMP simultaneously:
$ cmake -G "Ninja Multi-Config" -S ../src -B . \
-DPHITS_USE_HDF5:BOOL=ON \
-DHDF5_ROOT:PATH=$HOME/local/hdf5 \
-DPHITS_USE_OMP:BOOL=ON
To enable MPI:
$ cmake -G "Ninja Multi-Config" -S ../src -B . \
-DPHITS_USE_MPI:BOOL=ON -DMPI_Fortran_COMPILER:PATH=mpifort
Build
To build the executable for standard calculations, use the following command:
$ cmake --build . --config Release
The executable will be generated in the build/Release directory. Rename any existing executable
in the $PHITSPATH/bin directory, then move the newly generated executable to $PHITSPATH/bin.
If the standard version does not work, try the debug build:
$ cmake --build . --config Debug
The executable will be generated in the build/Debug directory. Follow the same steps to move it
to the $PHITSPATH/bin directory.
10.3. Linux¶
10.3.1. Installing Compilers and Libraries¶
On Linux, ifx requires you to download and install the Intel oneAPI Toolkit from https://www.intel.com/content/www/us/en/developer/tools/oneapi/oneapi-toolkit.html. After installation, set the environment variables with the following command. This example assumes Ubuntu 24.04.
$ source /opt/intel/oneapi/setvars.sh
Installing cmake:
$ sudo apt install cmake ninja-build
10.3.2. Installing Libraries¶
Parallel computing using MPI requires the Intel OneAPI’s MPI. Reading and writing files in HDF5 format requires HDF5. HDF5 has been tested with version 1.14.6. If you install HDF5 using a package manager such as apt, PHITS with HDF5 enabled cannot be compiled with ifx.
Download the version built for Intel OneAPI from the developer. The following instructions assume installation in the $HOME/local directory.
$ wget https://github.com/HDFGroup/hdf5/releases/download/hdf5_1.14.6/hdf5-1.14.6-ubuntu-2404_intel.tar.gz
$ tar xf hdf5-1.14.6-ubuntu-2404_intel.tar.gz
$ tar xf hdf5/HDF5-1.14.6-Linux.tar.gz
$ mkdir -p local
$ cp -a HDF5-1.14.6-Linux/HDF_Group/HDF5/1.14.6 local/hdf5
If there isn’t a prebuilt version for Intel oneAPI, get the source code for HDF5 and build it.
$ wget https://github.com/HDFGroup/hdf5/releases/download/hdf5_1.14.6/hdf5-1.14.6.tar.gz
$ tar xf hdf5-1.14.6.tar.gz
$ mkdir build
$ cd build
$ cmake -S ../hdf5-1.14.6 -B . -G Ninja --preset=ci-StdShar-Intel \
-DCMAKE_INSTALL_PREFIX:PATH=$HOME/local/hdf5 \
-DCMAKE_TOOLCHAIN_FILE:STRING=config/toolchain/intel.cmake \
-DHDF5_BUILD_FORTRAN:BOOL=ON \
-DHDF5_BUILD_JAVA:BOOL=OFF \
-DHDF5_ENABLE_PLUGIN_SUPPORT:BOOL=OFF
$ cmake --build . --target install
$ echo "export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:$HOME/local/hdf5/lib" >> ~/.bashrc
These libraries are also required at runtime; do not delete or rename their directories after installation.
10.3.3. Building PHITS¶
It is assumed that the PHITS source code resides in the src directory and the build
directory is used for the build process, both located at the same directory level.
Create a build directory and move into it
$ mkdir ${PHITSPATH}/build
$ cd ${PHITSPATH}/build
Build Configuration
To build for a single core as an example, execute the following command:
$ cmake -G "Ninja Multi-Config" -S ../src -B .
You can enable parallelization with OpenMP or MPI, or enable HDF5
support by adding specific options. These options can be combined. When using HDF5 and
OpenMP simultaneously, please specify an HDF5 build with thread-safety enabled.
If you have multiple Fortran compilers installed, such as ifx and gfortran, you can specify the compiler using the -DCMAKE_Fortran_COMPILER option.
Feature |
Option or Variable |
|
|---|---|---|
Enable HDF5 |
|
$HOME/local/hdf5)” |
Parallelization via OpenMP |
|
|
Parallelization via MPI |
|
|
Fortran compiler specification |
|
To enable HDF5:
$ cmake -G "Ninja Multi-Config" -S ../src -B . \
-DPHITS_USE_HDF5:BOOL=ON -DHDF5_ROOT:PATH=$HOME/local/hdf5
To use HDF5 and OpenMP simultaneously:
$ cmake -G "Ninja Multi-Config" -S ../src -B . \
-DPHITS_USE_HDF5:BOOL=ON -DHDF5_ROOT:PATH=$HOME/local/hdf5 \
-DPHITS_USE_OMP:BOOL=ON
Build
To build the executable for standard calculations, use the following command:
$ cmake --build . --config Release
The executable will be generated in the build/Release directory. Rename any existing executable in the
$PHITSPATH/bin directory, then move the newly generated executable to $PHITSPATH/bin.
If the standard version does not work, try the debug build:
$ cmake --build . --config Debug
The executable will be generated in the build/Debug directory. Follow the same steps to move it to
the $PHITSPATH/bin directory.
10.4. Compilation with KURBUC¶
The actual source code of proton and ion track structure simulation module, kurbuc.f, is not included in src folder with respect to its copyright.
Thus, kurbuc.f included in src folder is a dummy file, and executable file of PHITS created by the normal compilation process cannot perform the proton and ion track structure simulation.
If you want to perform proton and ion track structure simulation using your own PHITS executable file, you must replace the object file of kurbuc, kurbuc.o or kurbuc.obj, by that corresponding to your machine environment included in src/kurbuc-obj folder, and re-create the PHITS executable file.
The easiest way to re-create PHITS executable file is to save a source file of PHITS, for example main.f, and compile PHITS again.
If you cannot find an object file suitable to your machine environment or have problem with re-creating PHITS executable file using our provided object file, please contact PHITS office.
10.5. Array sizes¶
The array sizes described in param.inc file may need to be checked and modified.
The important variables you may need to change in param.inc are kvlmax (maximum number of cells and materials), itlmax (maximum number of tally entries), and isrc (maximum number of multi-sources).
The default param.inc is shown below.
************************************************************************
* *
* 'param.inc' *
* *
************************************************************************
! when you increase mdas over 250000000, you have to define integer*8 instead of integer in the next line
integer mdas,mcmx,mci,mmdas,mmmax,nbnds,mct,multmax,pnlmax
integer kvlmax, kvmmax, itlmax, inevt, isrc, nbchmax, maxchapara
integer mxprodxs
real*8 das
parameter ( mdas = 80000000 )
parameter ( kvlmax = 3000 )
parameter ( kvmmax = 1000000 )
parameter ( itlmax = 200 )
parameter ( inevt = 71 )
parameter ( isrc = 3000 )
parameter ( nbchmax= 10000 )
parameter ( multmax= 500 )
parameter ( pnlmax = 3000 )
parameter ( maxchapara = 1000 )
parameter ( mxprodxs = 20000 )
*----------------------------------------------------------------------*
* *
* pnlmax : maximum number of material in photonuclear library *
* *
*----------------------------------------------------------------------*
common /mdasa/ das( mdas )
common /mdasb/ mmmax
*----------------------------------------------------------------------*
* *
* mdas : total memory * 8 = byte *
* mmmax : maximum number of total array *
* *
* kvlmax : maximum number of regions, cell and material *
* kvmmax : maximum number of id for regions, cel and material *
* *
* itlmax : number of maximum tally entry *
* inevt : number of collision type for summary *
* isrc : number of multi-source *
* nbchmax: maximum number of batch assigned to parallel MPI node *
* pnlmax : maximum number of material in photonuclear library *
* mxprodxs : maximum number of produced nuclides in prodxs *
* *
*----------------------------------------------------------------------*