.. _sec-installation_mac:

Installation and Execution on Mac OS
==================================================

Before Installation
------------------------------

Ghostscript is required to view EPS files created by PHITS. If Ghostscript is not installed, on machines with internet access and using Homebrew or MacPorts package manager, the PHITS installer will automatically install Ghostscript. On machines without a package manager, the Ghostscript installer included in the PHITSXXX folder will launch, and you can follow the on-screen instructions.

To install PHITS, you need a 7zip-based command such as :command:`7zz` or :command:`7z`. This will speed up the installation. On machines using Homebrew or MacPorts package manager, the PHITS installer will automatically install :program:`7zip`. On machines without a package manager, the PHITS installer will use the :command:`tar` command included in macOS.

Installation Procedure
--------------------------------------------------

Recommendation method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Give :program:`Terminal.app` Full Disk Access permission in **System Settings** > **Privacy & Security** . :program:`Terminal.app` is located in the :file:`Utilities` folder inside the :file:`Applications` folder.

   .. figure:: mac-full_disk_access.png
      :width: 40em
      :alt: full disk access on Mac
      :name: mac-full-disk-access

      Granting full disk access to :program:`Terminal.app`.

#. Extract the zip file downloaded from the office, and inside the :file:`PHITSXXX` folder that appears, go to the :file:`mac` folder. Right-click (or secondary click, two-finger tap on a trackpad, or control click; hereafter referred to as right-click) on :program:`PHITS_Installer.command` and select "Open" from the shortcut menu.

   .. figure:: mac-installer_command.png
      :width: 40em
      :alt: installer command on Mac
      :name: mac-installer-command

      Launching :program:`PHITS_Installer.command`

#. For macOS 14 Sonoma and earlier, a dialog will appear asking you to confirm whether you want to open this application because it is from an unverified developer; click :guilabel:`Open`.

   .. figure:: mac-unknown_dev.png
      :width: 40em
      :alt: unknown developer on Mac
      :name: mac-unknown_dev

      A dialog box asking for confirmation whether to open because the developer has not verified it.

#. If you are using macOS 15 Sequoia or later, when you right-click :program:`PHITS_Installer.command` ,
   a dialog box may appear saying that it is not open. Click :guilabel:`Done`.

   .. figure:: mac-installer_not_opened.png
      :width: 40em
      :alt: installer not opened on Mac
      :name: mac-installer-not-opened

      A dialog box indicating that :program:`PHITS_Installer.command` is not opened.

#. Under :guilabel:`Privacy & Security` in :program:`System Settings`, click :guilabel:`Open Anyway` to the right of :program:`PHITS_Installer.command` was blocked to protect your Mac.

   .. figure:: mac-open_anyway.png
      :width: 40em
      :alt: installer not opened on Mac
      :name: mac-open-anyway

      A dialog box indicating that :program:`PHITS_Installer.command` is not opened.

#. If a dialog box appears prompting you to enter an administrator username and password, follow
   the instructions.

   .. figure:: mac-admin_dialog.png
      :width: 40em
      :alt: Administrator dialog on Mac
      :name: mac-admin-dialog

      A dialog box prompting for the administrator username and password.

#. If you cannot start :program:`PHITS_Installer.command`, open a terminal, navigate to the directory where :program:`PHITS_Installer.command` is located, and execute the following command. Then, right-click :program:`PHITS_Installer.command` and select :guilabel:`Open` from the shortcut menu.

.. code-block:: console

   $ chmod 755 PHITS_Installer.command

#. If Ghostscript is not installed and a package manager is not available, the Ghostscript installation window will be displayed. Follow the instructions on the screen. If Ghostscript is installed or a package manager is available, this screen will not be displayed.

#. When selecting the installation mode, select **Automatic** . Select **Manual** if Automatic does not work properly.

   .. figure:: mac-mode.png
      :width: 40em
      :alt: installation mode on Mac
      :name: mac-mode

      Selecting an installation mode

#. Specify the destination folder for installation. Usually, the folder with the same name as your account name ( **alex** in the screenshot below) is selected, so press :guilabel:`Select`.

   .. figure:: mac-location.png
      :width: 40em
      :alt: installation location on Mac
      :name: mac-location

      Select the installation folder.

#. After the installation is complete, reboot the system.

#. A folder named :file:`phits` will be created in the installation destination. It contains PHITS main body, source code, seminar materials, examples, etc.

.. tip::
   - If you move the :file:`phits` folder to another folder after installation, PHITS will no longer work. Please install it again.
   - If a folder named :file:`phits` exists in the installation destination, the old folder will be renamed to phits[today's date].[current time].
   - If the name of the folder where you copy the PHITS package or the name of the installation folder contains spaces or Chinese characters, an error may occur. Please install the package in a folder that does not contain such characters.

What to do if the recommended method fails
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Create a :file:`phits` folder in your home directory (:file:`/Users/alex` if your account name is **alex** ).
- Extract the zip file downloaded from the office and copy :file:`phits.7z` in the phitsXXXA folder into the :file:`phits` folder.
- Double-click the copied :file:`phits.7z` to extract it.
- Double-click :file:`PHITS.Router.app.zip`` in the :file:`phitsXXX/mac` folder to unzip it. Move the resulting :file:`PHITS.Router.app` to the :file:`/Applications` folder.
- Right-click :program:`PHITS_Installer.command` in the :file:`PHITSXXX/mac` folder and select "Open" from the shortcut menu.
- When choosing the installation mode, select **Manual**.
- Select :file:`phits252_mac.exe` in the :file:`phits/bin` folder and start the installation.

If you are unable to install PHITS this way, please see :numref:`sec-mac-installation-exception` .

.. _sec-mac-installation-exception:

If none of the above methods work
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Make PHITS executable from the terminal. If you are running PHITS from the terminal for the first time, you need to add the path to the folder that contains the PHITS executable file. To add the path, enter the following command in the terminal:

.. code-block:: console

   $ echo 'export PHITSPATH=/PATH-TO-PHITS/phits' >> .zshenv
   $ echo 'export PATH=$PHITSPATH/bin:$PHITSPATH/dchain-sp/bin:$PATH' >> .zshenv
   $ source .zshenv

Here, change "/PATH-TO-PHITS" to the name of the installation folder (for example, :file:`/Users/alex` if your account name is **alex** ). If you do not know what PATH-TO-PHITS is, enter the following when you start the terminal.

.. code-block:: console

   $ find $HOME -name phits_mac

The result of this command, with :file:`/phits/bin` removed, corresponds to PATH-TO-PHITS. Note that this PATH setting is only required the first time you run PHITS; it is not necessary thereafter.

Next, grant execution permission to the executable file. Run the following command in the terminal.

.. code-block:: console

   $ chmod 755 $PHITSPATH/bin/* $PHITSPATH/dchain-sp/bin/*
   $ chmod 755 $PHITSPATH/phig3d/macos-universal/phig3d.app/Contents/MacOS/phig3d
   $ chmod 755 $PHITSPATH/phitspad/macos/PhitsPad.app/Contents/MacOS/phitspad
   $ xattr -d -r com.apple.quarantine $PHITSPATH/bin/* $PHITSPATH/dchain-sp/bin/*
   $ xattr -d -r com.apple.quarantine $PHITSPATH/phitspad/macos-universal/phig3d.app/Contents/MacOS/phig3d
   $ xattr -d -r com.apple.quarantine $PHITSPATH//phitspad/macos/PhitsPad.app/Contents/MacOS/phitspad

Execution
--------------------------------------------------

Once the installation of PHITS is complete, the :program:`PHITS Router`` icon will be added to the dock.

.. figure:: mac-dock_icon.png
   :width: 40em
   :alt: Dock icon on Mac
   :name: mac-dock_icon

   The icon for :program:`PHITS Router` has been added to the dock.

File Associations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Right-click the PHITS input file :file:`phits/lecture/basic/lec01/lec01.inp`, select **Open with**, and
then select :guilabel:`Other` .

.. figure:: mac-file_association0.png
   :width: 40em
   :alt: file association on Mac
   :name: mac-file_association0

   Input file association

In the file selection dialog, select :program:`PHITS Router` and click "Open".

.. figure:: mac-file_association1.png
   :width: 40em
   :alt: file association on Mac
   :name: mac-file_association1

   Input file association

Execution of PHITS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. rubric:: Drag and drop execution

Drag and drop a PHITS input file such as :file:`lec01.inp` onto the PHITS Router in the dock.

.. figure:: mac-phits.png
   :width: 40em
   :alt: launch PHITS on Mac
   :name: mac-phits

   Selecting a PHITS

When you start the app for the first time, you will be asked for permission to allow :program:`PHITS Router`
to control :program:`Terminal.app`. Please allow it.

.. figure:: mac-phits_1st.png
   :width: 40em
   :alt: 1st launch PHITS on Mac
   :name: mac-phits_1st

   dialog requesting permission to control :program:`Terminal.app`

This screen will appear, so select :guilabel:`PHITS` and click :guilabel:`OK`.

If you drag and drop the input file into :program:`PHITS Router` while holding down the :kbd:`⌘ Command` key, PHITS will be executed directly without displaying this screen.

A new terminal will open and display the calculation status. The calculation output file will be created in the same folder as the input file.

If you want to run the calculation again with the same input, press the :kbd:`↑ up arrow` key in the terminal where the calculation status is displayed, then press the return key.

.. rubric:: Running in Terminal

In the terminal, go to the directory where the input file is located and run the following command:

.. code-block:: console

   $ phits.sh <input file name>

example

.. code-block:: console

   $ phits.sh lec01.inp

Execution of PHITSPAD
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. rubric:: Drag and drop execution

Drag and drop a PHITS input file such as :file:`lec01.inp` onto :program:`PHITS Router` in the dock.

.. figure:: mac-phitspad.png
   :width: 40em
   :alt: PHITSPAD on Mac
   :name: mac-phitspad

   Selecting a PHITSPAD

This screen will appear, so select :guilabel:`PHITS-Pad` and press :guilabel:`OK`.

If you drag and drop the input file into :program:`PHITS Router` while holding down the :kbd:`⇧ Shift` key, :program:`PHITS-Pad` will launch directly without displaying this screen.

.. rubric:: Running in Terminal

In the terminal, go to the directory where the input file is located and run the following command:

.. code-block:: console

   $ phitspad.sh <input file name>

example

.. code-block:: console

   $ phitpad.sh lec01.inp

Execution of PHIG-3D
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. rubric:: Drag and drop execution

Drag and drop a PHITS input file such as :file:`lec01.inp` onto :program:`PHITS Router` in the dock.

.. figure:: mac-phig3d.png
   :width: 40em
   :alt: PHIG3D on Mac
   :name: mac-phig3d

   Selecting a PHIG3D

This screen will appear, so select :guilabel:`PHIG-3D` and click :guilabel:`OK`.

If you hold down the :kbd:`⌥ Option` key and drag and drop the input file into :program:`PHITS Router`, PHIG-3D will launch directly without displaying this screen.

.. rubric:: Running in Terminal

In the terminal, go to the directory where the input file is located and run the following command:

.. code-block:: console

   $ phig3d.sh <input file name>

example

.. code-block:: console

   $ phig3d.sh lec01.inp

Execution of ANGEL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Drag and drop execution**

Drag and drop the output file generated by PHITS, such as :file:`track_xz.out`, onto :program:`PHITS Router` in the dock.

.. figure:: mac-angel.png
   :width: 40em
   :alt: ANGEL on Mac
   :name: mac-angel

   Selecting an ANGEL

This screen will appear, so select :guilabel:`ANGEL` and click :guilabel:`OK`.

If you hold down the :kbd:`⌥ Option` key and drag and drop the input file into :program:`PHITS Router`, ANGEL will launch directly without displaying this screen.

.. rubric:: Running in Terminal

In the terminal, go to the directory where the input file is located and run the following command:

.. code-block:: console

   $ angel.sh <input file name>

example

.. code-block:: console

   $ angel.sh track_xz.out

Execution of DCHAIN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. rubric:: Drag and drop execution

Drag and drop the output file generated by PHITS, such as :file:`tdchain.out`, onto :program:`PHITS Router` in the dock.

.. figure:: mac-dchain.png
   :width: 40em
   :alt: DCHAIN on Mac
   :name: mac-dchain

   Selecting a DCHAIN

This screen will appear, so select :guilabel:`DCHAIN` and press :guilabel:`OK`.

If you drag and drop the input file into :program:`PHITS Router` while holding down the :kbd:`⌘ Command` key, DCHAIN ​​will launch directly without displaying this screen.

.. rubric:: Running in Terminal

In the terminal, go to the directory where the input file is located and run the following command:

.. code-block:: console

   $ dchain.sh <input file name>

example

.. code-block:: console

   $ dchain.sh tdchain.out

Detailed instructions for using PHITS Router
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

PHITS Router allows you to configure your preferred text editor. For details, see `<https://github.com/Lindt8/phits-router-macos>`_ .

Viewing EPS files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. rubric:: Recommendation method

- Double-click on the EPS file.
- If you double-click multiple EPS files at the same time, each file will be converted to PDF and displayed.

.. rubric:: If you can't open it by double-clicking

If the following screen appears when you double-click an EPS file, please follow the steps below.

.. figure:: mac-no_eps_app.png
   :width: 40em
   :alt: no eps app on Mac
   :name: mac-no_eps_app

   A dialog box appears stating that there is no application to open the EPS file

In the screen above, click "Choose Application". Select :file:`phits/bin/EPSPDF.app` in the file selection dialog.

.. figure:: mac-epspdf_location.png
   :width: 40em
   :alt: epspdf location on Mac
   :name: mac-epspdf_location

   Dialog to select :file:`EPSPDF.app`

.. tip::
   - Double-clicking any EPS file, not just EPS files created by PHITS or ANGEL, will open the file in preview via this application.
   - If you want to open the EPS file in a different application, right-click on it and select "Open with" and choose the application you want to use.