.. _sec-compile: ************************************************** How to Build PHITS ************************************************** If you use the user-defined source ``usrsors.f`` or **[t-userdefined]**, PHITS must be compiled. The compilers that have been verified by the PHITS office are Intel oneAPI and gfortran. Except for macOS, which is not supported, the use of Intel oneAPI is recommended. Please note that sufficient support cannot be provided for issues arising from the use of other compilers. :numref:`tbl-compile` summarizes the combinations of compilers and settings available for each operating system. Here, single indicates execution without parallelization, while MPI and OpenMP represent parallel execution using the MPI protocol and OpenMP, respectively. hybrid denotes a configuration that combines these parallelization methods. For details on parallel computation, see :numref:`sec-parallel`. .. _tbl-compile: .. list-table:: Supported compiler and configuration combinations for each operating system :header-rows: 2 * - 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 [#gfortran-openmp]_ - * - Mac - - - - - yes - - yes [#gfortran-openmp]_ - * - Linux - yes - yes - yes - yes - yes - - yes [#gfortran-openmp]_ - .. [#gfortran-openmp] The OpenMP performance with gfortran is not very high. .. _sec-compile-Win: Build Procedure on Windows OS ================================= Installation of Compilers and Libraries -------------------------------------------------- On Windows, the Intel oneAPI ifx compiler is used as the Fortran 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 [#]_ and ninja [#]_ 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 [#]_, it should also be installed separately. However, since some issues occur in version 2.0.0 and later, please use version 1.14.6 [#]_. .. [#] https://cmake.org/ .. [#] https://ninja-build.org/ .. [#] https://www.hdfgroup.org/solutions/hdf5/ .. [#] https://support.hdfgroup.org/releases/hdf5/v1_14/v1_14_6/downloads/index.html Building PHITS -------------- 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. .. code-block:: console cd C:\phits\src\cmake The PHITS Fortran source files are located in ``C:\phits\src``. Since the CMake-related files are located in the ``cmake`` folder, move to that 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``. .. list-table:: Available Options :header-rows: 1 * - Option - Description * - -S - Specifies the folder containing ``CMakeLists.txt`` (a dot ``.`` means the current directory). * - -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 ``cmake --help``). * - -DCMAKE_BUILD_TYPE:STRING - Sets the build type (Release or Debug). When Debug is specified, PHITS is built in debug mode, producing ``phits_win_dbg.exe``. * - -DCMAKE_RUNTIME_OUTPUT_DIRECTORY - Specifies the output directory for the executable files. * - -DPHITS_ADD_SUFFIX - Specifies whether to append the suffix ``_win`` to the executable name (=yes to append, =no otherwise). * - -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 ``-T "fortran=ifx"``. 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. .. code-block:: console 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 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. .. code-block:: console 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: .. code-block:: console cmake --build build_multi --config Release or .. code-block:: console 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. Single Mode (Option 2) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When using Visual Studio as the generator, run the following CMake command: .. code-block:: console 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. Single Mode (Option 3) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To build PHITS with HDF5 enabled, add the ``-DPHITS_USE_HDF5=yes`` option to the ``cmake`` command as follows: .. code-block:: console 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 Single Mode (Option 4) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can also use gfortran as the Fortran compiler by specifying it with the ``-DCMAKE_Fortran_COMPILER`` option. .. code-block:: console cmake -S . -B build -G Ninja_gfortran -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. OpenMP Mode ~~~~~~~~~~~~~~~~~~~~~~~~ You can build PHITS with the following option. The executable file ``phits_openmp_win.exe`` will be generated. .. code-block:: console 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 MPI Mode ~~~~~~~~~~~~~~~~~~~~~~~~ You can build PHITS with the following option. The executable file ``phits_mpi_win.exe`` will be generated. .. code-block:: console 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 .. _sec-VisualStudio: 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. 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: .. code-block:: console @echo off title PHITS: %1 set PHITS_Single_EXE="%PHITSPATH%/bin/recompiled/phits_win.exe" set PHITS_MPI_EXE="%PHITSPATH%/bin/phits_win_mpi.exe" set PHITS_OpenMP_EXE="%PHITSPATH%/bin/phits_win_openmp.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. .. _sec-compile-Mac: macOS ================================= Introduction ------------- To build PHITS yourself, you must first install the compiler and required libraries, then proceed to the PHITS build process. Installing Compilers and Compilation Tools -------------------------------------------------- On macOS, :command:`gfortran` is used as the Fortran compiler. You can install :command:`gfortran` using either :program:`Homebrew` or :program:`MacPorts`. This section describes the method using :program:`Homebrew`. If you prefer :program:`MacPorts`, please refer to its official documentation. If :program:`Homebrew` is not installed, execute the following command in your terminal to install it: .. code-block:: console $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" Next, install the Fortran compiler along with :command:`cmake` and :command:`ninja`, which are used for the compilation process. .. code-block:: console $ brew install gcc cmake ninja Installing Libraries -------------------------------------------------- :program:`OpenMPI` is required for parallel computing via MPI and can be installed using :program:`Homebrew`. .. code-block:: console $ brew install open-mpi :program:`HDF5` is required to read tetrahedral mesh geometries in HDF5 format and is installed via :program:`Homebrew`. Operation has been verified with :program:`HDF5` version 1.14.6. .. code-block:: console $ 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 Building PHITS -------------- It is assumed that the PHITS source code resides in the :file:`src` directory and the :file:`build` directory is used for the build process, both located at the same directory level. #. Navigate to the build directory .. code-block:: console $ cd build #. Build Configuration To build for a single core as an example, execute the following command: .. code-block:: console $ cmake -G "Ninja Multi-Config" -S ../src -B . You can enable parallelization with :program:`OpenMP` or :program:`MPI`, or enable :program:`HDF5` support by adding specific options or variables to the command above. Multiple options can be specified simultaneously. .. csv-table:: Available Options and Variables :header: Feature, Option or Variable Parallelization via :program:`OpenMP`, ``-DPHITS_USE_OMP:BOOL=ON`` Parallelization via :program:`MPI`, ``-DPHITS_USE_MPI:BOOL=ON -DMPI_Fortran_COMPILER:PATH=mpifort`` Enable :program:`HDF5`, ``-DPHITS_USE_HDF5:BOOL=ON`` To enable HDF5, use the following: .. code-block:: console $ cmake -G "Ninja Multi-Config" -S ../src -B . \ -DPHITS_USE_HDF5:BOOL=ON \ -DHDF5_ROOT:PATH=$HOME/local/hdf5 To use :program:`HDF5` and :program:`OpenMP` simultaneously: .. code-block:: console $ 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 :program:`MPI`: .. code-block:: console $ 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: .. code-block:: console $ 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: .. code-block:: console $ 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. .. _sec-compile-Lin: Linux ================================= Installing Compilers and Libraries -------------------------------------------------- On Linux, Intel oneAPI's :command:`ifx` is used as the Fortran compiler. Please download and install the Intel oneAPI Base Toolkit and Intel oneAPI HPC Toolkit from https://www.intel.com/content/www/us/en/developer/tools/oneapi/toolkits.html . After installation, set the environment variables with the following command (assuming Ubuntu 24.04): .. code-block:: console $ source /opt/intel/oneapi/setvars.sh Installing cmake: .. code-block:: console $ sudo apt install cmake ninja-build Installing Libraries -------------------------------------------------- Intel oneAPI :program:`MPI` is required for parallel computing via :program:`MPI`. :program:`HDF5` is required to read tetrahedral mesh geometries. Since installing :program:`HDF5` via package managers like :command:`apt` may cause compilation issues with :command:`ifx`, you should build :program:`HDF5` from source. The following instructions assume installation in the :file:`$HOME/local` directory. These libraries are also required at runtime; do not delete or rename their directories after installation. Operation has been verified with :program:`HDF5` version 1.14.6. .. code-block:: console $ 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 Building PHITS -------------- It is assumed that the PHITS source code resides in the :file:`src` directory and the :file:`build` directory is used for the build process, both located at the same directory level. #. Navigate to the build directory .. code-block:: console $ cd build #. Build Configuration To build for a single core as an example, execute the following command: .. code-block:: console $ cmake -G "Ninja Multi-Config" -S ../src -B . You can enable parallelization with :program:`OpenMP` or :program:`MPI`, or enable :program:`HDF5` support by adding specific options. These options can be combined. When using :program:`HDF5` and :program:`OpenMP` simultaneously, please specify an :program:`HDF5` build with thread-safety enabled. .. csv-table:: Available Options :header: Feature, Option or Variable Enable HDF5, ``-DPHITS_USE_HDF5:BOOL=ON -DHDF5_ROOT=`` "Installation directory (e.g., $HOME/local/hdf5)" Parallelization via OpenMP, ``-DPHITS_USE_OMP:BOOL=ON`` Parallelization via MPI, ``-DPHITS_USE_MPI:BOOL=ON -DMPI_Fortran_COMPILER:STRING=mpiifx`` To enable :program:`HDF5`: .. code-block:: console $ cmake -G "Ninja Multi-Config" -S ../src -B . \ -DPHITS_USE_HDF5:BOOL=ON -DHDF5_ROOT:PATH=$HOME/local/hdf5 To use :program:`HDF5` and :program:`OpenMP` simultaneously: .. code-block:: console $ 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: .. code-block:: console $ 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: .. code-block:: console $ 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. 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. .. _array-scale: 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. .. code-block:: text :caption: ``param.inc`` ************************************************************************ * * * '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 * * * *----------------------------------------------------------------------*