インストールマニュアル
==========================

.. contents:: 目次:
    :depth: 3

概要
#####################################

RAIMのインストールは

* FRENDYのコンパイル
* RAIMのスクリプト生成

の2つの行程に分けられる。

本マニュアルではUbuntuへのインストール方法について説明する。

環境構築
#####################################

FRENDYをコンパイルするためにいくつかのソフトウェアのインストールが必要となる。
また、Ubuntu24.04など比較的新しい環境では、Pythonは仮想環境上で実行することを前提としているため、
一部のライブラリがシステムのPythonにインストールできなくなっている。
そのため、FRENDYのコンパイルおよびRAIMの実行のためにPythonの仮想環境を構築する方法についても説明する。

ソフトウェアのインストール
*************************************

FRENDYのコンパイルに必要なソフトウェアをインストールする。

.. code-block:: sh

    sudo apt install python3-dev gcc g++

venvによる仮想環境の構築
*************************************

システムにvenvをインストールする。

.. code-block:: sh

    sudo apt install python3-venv

.. note::

    上記のコマンドでpython3-venvが見つからない場合、以下のコマンドでパッケージリストを更新する必要がある。

    .. code-block:: sh

        sudo apt update

venvを用いて仮想環境を作成する。
例えば、HOMEディレクトリに :file:`.venv` という隠しフォルダを作成し、そこに仮想環境を作成する場合、以下のコマンドを実行する
（仮想環境を作成するフォルダのパスおよび名前は任意である）。

.. code-block:: sh

    python3 -m venv ~/.venv

次に、仮想環境を有効化する。

.. code-block:: sh

    source ~/.venv/bin/activate

仮想環境を有効化すると、ターミナル上に仮想環境名が表示されるようになる。
また、ディレクトリを移動しても仮想環境は有効のままである。
この状態で `python` コマンドを実行すると、仮想環境におけるPythonが呼び出され、インタプリタが起動する。
また、 `pip` コマンドを打つと、仮想環境におけるpipが実行され、仮想環境のPythonにライブラリがインストールされる。

仮想環境を無効化する場合は以下のコマンドを実行する。

.. code-block:: sh

    deactivate

仮想環境が無効化すると、ターミナル上の仮想環境名は表示されなくなる。

ディレクトリ構成
#####################################

任意のディレクトリにソースコード（raim.zip）を展開する。
コマンドラインから展開する場合は以下のコマンドを実行する。

.. code-block:: sh

    unzip -P xxxx raim.zip  # xxxxはパスワード

:file:`raim` には以下のフォルダが含まれている。

.. csv-table:: ディレクトリ構成
   :header-rows: 1
   :widths: 40, 60
   :name: directory_structure

   フォルダ, 説明
   raim, RAIMルートディレクトリ
   raim/src/cpp/frendy, FRENDYソースコード
   raim/src/python/lib, RAIMソースコード
   raim/src/python/script, RAIMスクリプトファイル
   raim/input, インプットファイル
   raim/data/measurement, 測定データ
   raim/data/pulse, パルス関数設定ファイル
   raim/shellscript, RAIM実行用シェルスクリプト
   raim/profiles, conanプロファイル
   raim/util, ユーティリティスクリプト

FRENDYのコンパイル
#####################################

Conanを用いた方法（推奨）
*************************************

C/C++パッケージマネージャー **Conan** をPythonにインストールする。

.. code-block:: sh

    pip install conan

RAIMルートディレクトリ :file:`raim` において、ConanによるC/C++ライブラリのインストールとC/C++コードのビルドを行う。
Conanを用いることでC/C++コードのビルドに必要なソフトウェア・ライブラリ類を自動的にインストールすることができる。

.. code-block:: sh

    cd raim
    conan build . --profile:all profiles/linux_gcc_11_release

:file:`build/Release` に共有ライブラリが生成する。

- libFrendy.so
    - FRENDYの共有ライブラリ
- FrendyWrapper.cpython-\***-x86_64-linux-gnu.so
    - FRENDYのPythonラッパーの共有ライブラリ（\***にはPythonのバージョン番号が入る）

.. note::

    システムのPythonと仮想環境のPythonでバージョンが異なる場合、システムのPythonバージョンのFrendyWrapperが生成される場合がある。
    Pythonのバージョンを固定するには :file:`raim/CMakeLists.txt` のPythonパッケージを探す部分を以下の様に修正する（例：Python3.12に固定する場合）。

    .. code-block:: cmake

        find_package(Python3 EXACT 3.12 COMPONENTS Interpreter Development)


Conanを用いない方法
*************************************

自分で用意したC/C++ライブラリを使用したい場合などは、Conanを用いずに直接CMakeを用いてビルドを行う。

CMakeをインストールする。

.. code-block:: sh

    apt install cmake

C/C++ライブラリのBoost、Lapack、BLASはそれぞれ以下のコマンドでインストールを行うことが可能である。

.. code-block:: sh

    # Boostのインストール
    apt install libboost-all-dev
    # Lapack、BLASのインストール
    apt install liblapack-dev libblas-dev

.. note::

    Lapack、BLASについては上記の他にOpenBLASやATLASを使用することも可能である。

    .. code-block:: sh

        # OpenBLASをインストールする場合
        apt install libopenblas-dev
        # ATLASをインストールする場合
        apt install libatlas3-base libatlas-base-dev

また、RAIMではC++で記述されたFRENDYの機能をPythonから呼び出すために **pybind11** というPythonのモジュールを使用する。
RAIMを実行する際に利用するPythonのpipでpybind11をインストールする。

.. code-block:: sh

    pip install pybind11

共有ライブラリを出力するフォルダ :file:`build/Release` を作成して移動し、CMakeによるビルドを行う。
出力先フォルダを変更する場合、RAIM実行用シェルスクリプトの修正が必要となる。

.. code-block:: sh

    # 出力先フォルダの作成
    mkdir -p build/Release
    cd build/Release
    # CMakeプロジェクトファイルの生成、pybind11へのパスを指定する
    cmake -Dpybind11_DIR=/path/to/pybind11/share/cmake/pybind11 ../..
    # ビルド
    cmake --build .

.. note::

    Conanを用いた方法ではNinjaという高速なビルドシステムを用いているが、この方法ではデフォルトのMakeを用いるためビルドに時間がかかる。
    CMakeのオプションでNinjaに切り替えることも可能なので、必要に応じて変更する。

Conanを用いた場合と同様に、共有ライブラリが生成される。

.. _make_run_scripts:

RAIMのスクリプト生成
#####################################

RAIMルートディレクトリ :file:`raim` において、インストール用スクリプトを実行する。

.. code-block:: sh

    cd raim
    ./install.sh

:file:`raim/shellscript` にRAIM実行用シェルスクリプトが生成する。

Pythonライブラリの追加
#####################################

RAIMを実行するためにはいくつかのライブラリ、モジュールをインストールする必要がある。

.. code-block:: sh

    pip install numpy scipy matplotlib