Documentation Status

docs/source/images/gprMax_logo_small.png

始める

gprMaxとは?

gprMax は電磁波伝搬をシミュレートするオープンソースのソフトウェアです。 3次元のマクスウェル方程式をFDTD(Finite-Difference Time-Domain)法を用いて解きます。gprMaxは地中レーダ(Ground Penetrating Radar, GPR)のモデリングのために設計されましたがそれだけではなく、電磁波伝搬モデルとして他の応用にも用いられています。

gprMaxは現在、 GNU一般公衆ライセンス バージョン3 またはそれ以上のライセンス で公開されています。

gprMaxは主に Python 3 で書かれています。パフォーマンスが重視される部分は Cython. で書かれています。OpenMP を用いて並列化されたCPUベースのソルバーと、 NVIDIA CUDA を使用して記述されたGPUベースのソルバーが含まれています。

gprMaxを使用されましたか? 引用してください

gprMaxを使用したご自身の研究を発表される場合は、 以下のように私たちの研究を引用していただけると幸いです:

  • Warren, C., Giannopoulos, A., & Giannakis I. (2016). gprMax: Open source software to simulate electromagnetic wave propagation for Ground Penetrating Radar, Computer Physics Communications (http://dx.doi.org/10.1016/j.cpc.2016.08.020)

gprMaxの参照に関する詳細は ウェブサイトの出版物ページ をご覧ください。

パッケージの概要

gprMax/
    conda_env.yml
    CONTRIBUTORS
    docs/
    gprMax/
    gsoc/
    LICENSE
    README.rst
    setup.cfg
    setup.py
    tests/
    tools/
    user_libs/
    user_models/

  • conda_env.yml はAnaconda (Miniconda)の設定ファイルでgprMaxにすべての必要なPythonパッケージを含むPython環境をセットアップします。

  • CONTRIBUTORS にはgprMaxコードベースに貢献した人々の名前のリストが含まれています。

  • docs はユーザーガイドのソースファイルが含まれています。 ユーザーガイドは reStructuredText のマークアップを用いて書かれています。また Sphinx と Read the Docs を使ってビルドされています。

  • gprMax がメインパッケージです。 gprMax.py はパッケージにはメインモジュールです。

  • gsoc は Google Summer of Code プログラムのプロジェクトアイデアと提案の手引についての情報が含まれています。

  • LICENSE contains information on the GNU一般公衆ライセンス バージョン3 またはそれ以上のライセンス に関する情報が含まれています。

  • README.rst はインストール手順、利用方法、新機能と変更に関する 情報が含まれています。

  • setup.cfg はflake8を使用したコードフォーマットとスタイリングの環境設定が含まれています。

  • setup.py は Cython 拡張モジュールをコンパイルするために使用されます。

  • tests はテストモジュールと入力ファイルを含むサブパッケージです。

  • tools はモデルから出力された後処理を補助するスクリプトを含むサブパッケージです。

  • user_libs はユーザーから提供された有用なサブパッケージです。

  • user_models はユーザーから提供された有用な入力ファイルが格納されるサブパッケージです。

インストール

gprMaxをインストールする手順について説明します。:

  1. Pythonと必要なPythonパッケージをインストールし、GitHubからgprMaxのソースコードを手に入れます。

  2. OpenMPをサポートするCコンパイラのインストール

  3. gprMaxのビルドとインストール

インストールと更新手順をデモンストレーションした スクリーンキャスト を視聴できます。

1. Pythonと必要なPythonパッケージをインストールし、gprMaxのソースコードを取得する

gprMaxのためにPythonと必要なPythonパッケージをインストールする自己完結のPython環境として私達はMinicondaを推奨します。 Minicondaは Anacondaのミニバージョンで 完全に自由(商用利用と再配布を含む)なPythonディストリビューションです。それは科学, 数学, 工学とデータ解析のための300以上の主なPythonパッケージを含んでいます。

  • Minicondaをダウンロードしインストール します。 あなたのプラットフォームにあった Python 3.x バージョンを選択します。 私達はインストールオプションとしてあなたのユーザーアカウントだけにMinicondaをインストールする設定を推奨します。; そしてMiniconda にあなたの PATH 環境変数を追加し; そして register Miniconda Pythonを as your default Pythonとして登録します。 Minicondaのインストールのヘルプとして クイックインストールページ を見てください。

  • ターミナル (Linux/macOS) または コマンドプロンプト (Windows) を開き、 以下のコマンドを実行します。:

$ conda update conda
$ conda install git
$ git clone https://github.com/gprMax/gprMax.git
$ cd gprMax
$ conda env create -f conda_env.yml

condaが最新であることを確認し、Gitをインストールし、GitHubから最新のgprMax ソースコードを手に入れます。 そして、必要なすべてPythonパッケージを含むgprMax用の環境を作成します。

Anaconda/Minicondaを使用せず、Pythonと必要なPythonパッケージを手動でインストールしたい場合は、 conda_env.yml ファイルを確認してください。

Arch Linux (https://www.archlinux.org/) を利用している場合は (conda_env.yml) に wxPython を追加してインストールする必要があるかもしれません。

2. OpenMPをサポートするCコンパイラのインストール

Linux

  • 既に gcc はインストールされているため、 何もする必要はありません。

macOS

  • Xcode (macOSのIDE)にはLLVM (clang)コンパイラーが付属しているが、 現在はOpenMPをサポートしていないため, gcc をインストールする必要があります。 とはいえ, Xcode (with command line tools)はまだ有用でありインストールする。 App Storeからダウンロードできます。 Xcodeのインストール後に、 Homebrew パッケージマネージャー をダウンロードしてインストールし、gccをインストールするために, 以下を実行します:

$ brew install gcc

Microsoft Windows

  • Microsoft Build Tools for Visual Studio 2022 (direct link)をダウンロードしインストールします。 または Microsoft Visual Studio のダウンロードページ の'すべてのダウンロード'まで下にスクロールして 'Tools for Visual Studio 2022' の三角形を押して展開し、 'Build Tools for Visual Studio 2022' からダウンロードします。 インストール時に、 'Desktop development with C++' ワークロードを選択し、 'MSVC v143' と 'Windows 10 SDK' または 'Windows 11 SDK' を選択します。

  • Pathと環境変数を設定します。 これは Microsoftの指示 に従って実行します。 またはシステムPath環境変数に C:Program Files (x86)Microsoft Visual Studio2019BuildToolsVCToolsMSVC14.23.28105binHostx64x64 を手動で追加します。(これはマシンとインストール場所により変わります。)

あるいは別の方法として, Windows 10/11を使用している場合は、Windows Subsystem for Linux をインストールし、gprMaxをLinuxの手順に従いインストールします。 ただし、 現在の WSL はGnome, KDEなどのGUI デスクトップやアプリケーションをサポートしていません。

3. gprMaxのビルドとインストール

上記のツールをインストール後したら以下の手順でgprMaxをビルドしてインストールします。:

  • ターミナル (Linux/macOS) または コマンドプロンプト (Windows)を開き、gprMaxのtop-levelのディレクトに移動します。 もし有効となってなければ, condaのgprMax環境を conda activate gprMax で有効化します。以下のコマンドを 実行します。:

(gprMax)$ python setup.py build
(gprMax)$ python setup.py install

gprMaxを実行する準備が整いました。

gprMaxを実行する

gprMax は Pythonパッケージとして設計されており、つまり名前空間にディレクトリのように 複数のパッケージとモジュールがあります。

ターミナル (Linux/macOS) または コマンドプロンプト (Windows)を開き、 gprMaxのトップレベルディレクトリに移動します。condaのgprMax環境が有効されていないときには conda activate gprMax で有効化します。

gprMax の基本的な使用方法は以下となります。:

(gprMax)$ python -m gprMax path_to/name_of_input_file

一つのテストモデルを実行する例:

(gprMax)$ python -m gprMax user_models/cylinder_Ascan_2D.in

シミュレーション完了後にAスキャンをプロットできます。:

(gprMax)$ python -m tools.plot_Ascan user_models/cylinder_Ascan_2D.out

円柱状の金属のAスキャンの例であり、 入門/基本２次元モデルのページ の結果のようになります。

gprMaxの利用が完了したら、 conda環境を conda deactivate により非有効化します。

オプションのコマンドライン引数

引数名

型

説明

-n

integer

number of times to run the input file. This option can be used to run a series of models, e.g. to create a B-scan with 60 traces: (gprMax)$ python -m gprMax user_models/cylinder_Bscan_2D.in -n 60

-gpu

flag/list

flag to use NVIDIA GPU or list of NVIDIA GPU device ID(s) for specific GPU card(s), e.g. -gpu 0 1

-restart

integer

model number to start/restart the simulation from. It would typically be used to restart a series of models from a specific model number, with the -n argument, e.g. to restart from A-scan 45 when creating a B-scan with 60 traces: (gprMax)$ python -m gprMax user_models/cylinder_Bscan_2D.in -n 15 -restart 45

-task

integer

task identifier (model number) when running the simulation as a job array on Open Grid Scheduler/Grid Engine. For further details see the parallel performance section of the User Guide

-mpi

integer

number of Message Passing Interface (MPI) tasks, i.e. master + workers, for MPI task farm. This option is most usefully combined with -n to allow individual models to be farmed out using a MPI task farm, e.g. to create a B-scan with 60 traces and use MPI to farm out each trace: (gprMax)$ python -m gprMax user_models/cylinder_Bscan_2D.in -n 60 -mpi 61. For further details see the parallel performance section of the User Guide

--mpi-no-spawn

flag

uses MPI task farm without spawn mechanism. For further details see the parallel performance section of the User Guide

-benchmark

flag

switch on benchmarking mode. This can be used to benchmark the threading (parallel) performance of gprMax on different hardware. For further details see the benchmarking section of the User Guide

--geometry-only

flag

build a model and produce any geometry views but does not run the simulation, e.g. to check the geometry of a model is correct: (gprMax)$ python -m gprMax user_models/heterogeneous_soil.in --geometry-only

--geometry-fixed

flag

runs a series of models where the geometry does not change between models, e.g. a B-scan where only the position of simple sources and receivers, moved using #src_steps and #rx_steps, changes between models.

--opt-taguchi

flag

runs a series of models using an optimization process based on Taguchi's method. For further details see the user libraries section of the User Guide

--write-processed

flag

writes another input file after any Python code and include commands in the original input file have been processed. Useful for checking that any Python code is being correctly processed into gprMax commands.

-h or --help

flag

コマンドラインオプションのヘルプを表示

gprMaxの更新

  • ターミナル (Linux/macOS) または コマンドプロンプト (Windows)を開き、gprMaxのトップレベルディレクトリに移動し、 もしgprMaxのconda環境が有効化されていなければ、 conda activate gprMax により有効化します。 以下のコマンドを実行します。:

(gprMax)$ git pull
(gprMax)$ python setup.py cleanall
(gprMax)$ python setup.py build
(gprMax)$ python setup.py install

これはGitHubから最新のgprMaxソースコードを取得し、以前にビルドしたモジュールを削除/クリーニングし、 最新のgprMaxをビルドとインストールします。

condaとPythonパッケージの更新

定期的にcondaと必要なPythonパッケージを更新する必要あります。gprMax環境をdeactivatedしてgprMaxのトップレベルディレクトリに移動し、次のコマンドを実行します。:

$ conda update conda
$ conda env update -f conda_env.yml

貢献者の皆様に感謝 ✨🔗

https://contrib.rocks/image?repo=gprMax/gprMax