完全なインストール手順

：py:mod:gmxapi Python パッケージ Python パッケージのインストール手順（Gromacs 上で動作します）。

コマンドラインの例は、bash シェルを前提としています。

複数の|Gromacs|インストールについて

多くの|Gromacs|ユーザーは、同じコンピューターでHPCモジュールシステムと/または：ref:GMXRC <Gromacsへのアクセス>`構成スクリプトを使用して、複数の|Gromacs|インスタンスを切り替えています。 :py:mod:`gmxapi Pythonパッケージを使用して、同様の環境を切り替える場合は、各|Gromacs|インスタンスに対して、異なる：ref:Python仮想環境 <https://www.google.com/search?q=python+virtual+environment>`にインストールすることをお勧めします。 :py:mod:`gmxapi Pythonパッケージが構築された後、特定のコピーは常に同じ|Gromacs|インスタンスを参照します。

管理者権限なし：pip install

以下のドキュメントには、Python パッケージのインストールに頻繁にpip_ツールが参照されています。 状況によっては、権限のないユーザーはpip_にコマンドラインオプション --user を使用し、パッケージを Python のデフォルトのサイトパッケージディレクトリではなく、ユーザーのサイトパッケージディレクトリにインストールするように指示する必要があります。 このオプションは、仮想環境（推奨）で pip を実行する場合には適切ではありません。そのため、このドキュメントでは省略されています。 もし``--user``オプションが必要な場合は、コマンド例を pip install --upgrade somepackage --user のように変更してください。

Python 3 の実行ファイル名

これらの手順では、Python Runtime Services および pip という実行ファイル名を使用しています。これは、python3 または pip3 ではなく、Python の一部のインストールでは 3 という接尾辞が必要ですが、すでに Python の仮想環境をアクティブにしている場合は、通常は不要です（推奨）。

概要

通常、gmxapi Python パッケージのセットアップは、次の3つのステップに従います。この概要で十分な場合は、このドキュメントの残りの部分を省略できます。

インストール GROMACS

|Gromacs|のインストール場所を見つけ、インストールするか、ビルドしてインストールしてください。 |Gromacs| 2022以降のバージョンが推奨されます。

参考

GROMACS のインストール

以下の内容は、|Gromacs|が /path/to/gromacs にインストールされていることを前提としています。

Python の仮想環境をセットアップする

参考

Python の仮想環境をセットアップする

注釈

mpi4py は、追加の引数（コンパイラのヒント）が必要となる場合があります。詳細は：MPI の要件 を参照してください

python3 -m venv $HOME/myvenv
. $HOME/myvenv/bin/activate
python -m ensurepip --default-pip
pip install --upgrade pip setuptools wheel
pip install mpi4py

gmxapi Python パッケージのインストール

gmxapi パッケージを PyPI からダウンロードし、GROMACS のインストールディレクトリである /path/to/gromacs に合わせてビルドし、現在の環境の Python 環境にインストールします。

. /path/to/gromacs/bin/GMXRC
pip install --no-cache-dir gmxapi

参考

インストール

背景

gmxapi は、以下の3つの部分で構成されています:

  • GROMACS C++ 用の gmxapi ライブラリ。

  • このPythonパッケージは、Python 3.9以降をサポートしています。

  • MD 制約プラグインとサンプル gmxapi クライアントコード

GROMACS 必要なもの

Python パッケージは GROMACS のインストールを必要とします。既存の GROMACS のインストールを見つけ、または、手順を進める前に、「GROMACS の構築とインストール <http://manual.gromacs.org/documentation/current/install-guide/index.html>」を参照して、GROMACS を構築およびインストールしてください。

注釈

注意: gmxapi は、GROMACS が GMXAPI=ON および BUILD_SHARED_LIBS=ON で構成されていることを必要とします。これらのオプションは、ほとんどの場合、デフォルトで有効になっています。ただし、GROMACS のインストールでこれらのオプションが上書きされている場合は、gmxapi Python パッケージまたはその他のクライアントソフトウェアをビルドおよびインストールしようとすると、CMake エラーが表示されます。

もし、インストール時に GMXRC ファイルが存在する場合、「source」コマンドを使用して、通常どおりに :ref:`ファイルを参照<Gromacs|アクセス方法>`します。そうでない場合は、インストール場所を記録しておき、gmxapi パッケージをビルドする際に提供できるようにします。

ビルドシステム要件

gmxapi は Python 3.9 以バージョンのいずれでもビルドできます。

C++ 17 互換のコンパイラと、ある程度最新版の CMake が必要です。フル機能の gmxapi を使用するには、MPI コンパイラ (例: :command: mpicc) も必要となる場合があります。

重要：Pythonでインポートできるモジュールを構築するには、Pythonヘッダーを含むPythonのインストールが必要です。しかし、これらのヘッダーが存在するか、どこで入手できるかは、必ずしも明らかではありません。最も簡単な方法は、これらの手順に従ってPythonパッケージを構築してみることです。gmxapiが必要なPythonツールを見つけられない場合は、別のPythonのインストールを試すか、追加の開発パッケージをインストールしてください。

Linuxシステムでは、`python-dev`および/または`python3-dev`などのパッケージのインストールが必要になる場合があります。Pythonを、ゼロから構築する場合、または`pyenv install`のようなツールを使用して構築する場合（「Cpythonの構築方法（--enable-sharedを使用）<https://github.com/pyenv/pyenv/wiki#how-to-build-cpython-with---enable-shared>`_ 参照）、Python Cライブラリのインストールを`--enable-shared`フラグで有効にするようにしてください。あるいは、さまざまなPythonディストリビューションは、ユーザーのホームディレクトリへのインストールのみで、十分なビルド環境を提供します（以下に例を示します）。

もし、モジュールを通じて利用可能なソフトウェアを備えたHPCシステムを使用している場合、異なるPython環境を`module load`でロードし、動作するものを探すことができるかもしれません。

Python環境の要件

gmxapiはPython 3.9以降が必要です。バージョンを確認するには、次のコマンドを実行してください：:command:`python3 --version または :command:`python --version。

注釈

以下のドキュメントは、システム上でPython 3インタプリタにアクセスするために、末尾に「3」を追加する必要がないことを前提としています。システムにデフォルトでインストールされているPythonインタプリタは、python3`および`pip3`コマンドを使用する代わりに、`python`および`pip`コマンドを使用する可能性があります。バージョンを確認するには、`python3 --version、python --version、または`pip --version`コマンドを使用します。

ビルドとインストールには、cmake_、networkx_、setuptools_用のPythonパッケージが必要です（すべて`PyPIでpipを使用`（<https://pip.pypa.io/en/stable/>）から入手できます）。

完全な機能を利用するには、mpi4py_ と numpy_ もインストールする必要があります。これらの要件とバージョン番号は、requirements.txt に記載されています。

最も簡単な方法は、まず pip_ を更新してから、リポジトリに付属している :file: requirements.txt ファイルを使用することです。 このセクションのファイルパスは、ローカルコピーの GROMACS ソースのルートディレクトリからの相対パスです。

pip_ が利用可能であることを確認し、必要に応じて pip_ をインストールするか、インストール方法の手順を確認してください:

python -m ensurepip --default-pip

必要なコンポーネントのインストールまたはアップグレード:

python -m pip install --upgrade pip
pip install --upgrade setuptools wheel

"requirements"ファイルは、|Gromacs|ソースツリー内にあります

ローカルの GROMACS ソースリポジトリのソースコードからビルドする場合、requirements.txt を使用すると、gmxapi パッケージのインストール前に、必要な Python パッケージを事前にインストールできます。

pip install -r python_packaging/gmxapi/requirements.txt

ドキュメントの構築要件

参照してください：gmxapiドキュメントへのアクセス

テスト要件

注意: テストスイートは|Gromacs|のソースツリーのみで利用可能です。(これはインストールされたパッケージの一部ではありません。) |Gromacs|のソースは、`git`コマンドを使用するか、他の場所で説明されているようにアーカイブをダウンロードすることで取得できます。

テストは pytest を使用して実行されます。

python_packaging/gmxapi/requirements.txt には、テストに必要な追加の要件が記載されています。 pip を使用して:

pip install -r python_packaging/gmxapi/requirements.txt

フル機能のテストには、MPI並列環境も必要です。 mpi4py_ PythonパッケージとMPIランチャー（例：mpiexec, mpirun、HPCキューイングシステムの提供するもの、またはオペレーティングシステム用のお好みのMPIパッケージで提供されるもの）が必要です。

MPI の要件

アンセムシミュレーション機能を使用するには、MPI環境が必要です。

HPCシステムでは、これには、互換性のあるMPIツールとコンパイラセットをロードするために、通常は`:command:module load`コマンドを使用する必要があります。HPCのドキュメントを確認するか、module avail`コマンドを使用して、``openmpi`、mpich、または``mvapich``モジュールと対応するコンパイラモジュールを探してください。これは、次のような簡単な操作かもしれません:

module load gcc
module load mpicc

もし、すでに module load を使用して利用可能な GROMACS のインストールを使用している場合は、mpi4py パッケージを含む Python のインストールを見つけることを試みてください。 module システムは、ロードされたモジュール間のツールチェーンの互換性を通常は強制します。 module load で mpi4py または mpi4py を含む Python のインストールを使用する場合、通常はこのバージョンのパッケージを venv で使用したいでしょう。（Python の仮想環境をセットアップする を参照） module load で MPI を有効にした GROMACS のインストールを使用する場合、gmxapi は mpi4py の互換性を確認しようとします。

注意: 使用するビルドツールによって自動的にロードされるコンパイラが、最初に検出されたコンパイラとは異なる場合があるため、一貫性を保つために、コマンドラインでコンパイラを指定する必要がある場合があります。GROMACS、gmxapi、およびサンプルコードが同じコンパイラ(またはコンパイラセット)でコンパイルされるようにする必要がある場合があります。

注意: mpi4py を、Python および gmxapi Python パッケージ を構築するために使用されたツールセットとは異なるツールセットで構築した場合、予期しないエラーが発生することがあります。システムにデフォルトのコンパイラが Gromacs または gmxapi Python パッケージ に不十分な場合、OpenMPI または MPICH などのコンパイラを構築する必要がある場合があります。また、build mpi4py を特定の MPI コンパイララップと組み合わせて構築する必要がある場合もあります。これにより、Conda などの環境での構築が複雑になる可能性があります。Gromacs のツールチェーンとの MPI コンパイララップの一貫性を確認するには、mpicc --version コマンドの出力を、gmx --version コマンドで報告されるコンパイラ情報と比較してください。

``MPICC``環境変数をMPIコンパイララッパーに設定し、mpi4py_を強制的に再インストールしてください:

export MPICC=`which mpicc`
pip install --no-cache-dir --upgrade --no-binary ":all:" --force-reinstall mpi4py

もし、別のMPI Cコンパイララッパーを使用している場合は、上記の`:command:`mpicc`をそれらに置き換えてください。

「gmxapi」がインストール中にビルドシステムを設定する際、|Gromacs|のインストールとの「mpi4py」ツールの互換性を確認しようとします。互換性がない場合は、「CMake」メッセージが表示され、そこで「MPICC」を使用する可能性について提案が表示されます。（「pip」を使用している場合は、より詳細なビルド出力を得るために、「--verbose」オプションの使用を検討してください。）

Python パッケージのインストール

推奨されるのは、Pythonの`pip <https://pip.pypa.io/en/stable/>`パッケージインストーラを使用して、gmxapiパッケージの最新バージョンを自動的にダウンロード、ビルド、Pythonの`仮想環境 <https://docs.python.org/3/tutorial/venv.html>`にインストールすることです。ただし、仮想環境を使用せずにインストールすることも可能です。仮想環境を使用せずに、権限のないユーザーとしてインストールする場合は、pip install`コマンドで--user`オプションを使用する必要がある場合があります。

ソースからインストール

また、ローカルな GROMACS ソースリポジトリのコピーから、gmxapi Python パッケージをインストールすることも可能です。 GROMACS のソースコードを入手し、ソースツリーのルートディレクトリにいることを前提として、gmxapi Python パッケージのソースは、python_packaging/gmxapi ディレクトリにあります。

cd python_packaging/gmxapi
pip install -r requirements.txt
pip install .

オフラインでのインストール

推奨される手順:

:コマンド:`pip install --upgrade build pip setuptools wheel`

python -m build --skip-dependency-check コマンドを使用すると、ソース配布から gmxapi パッケージのみのバイナリ配布アーカイブを構築できます。ただし、その場合、ビルドおよびインストール環境の両方で、依存関係を手動で解決する必要があります。

インターネット接続がある間、gmxapi のソース配布と、必要なパッケージの依存関係へのアクセスが必要です。また、パッケージがビルドされる環境では、wheel と build パッケージも必要です。gmxapi の wheel が作成された後は、pip のみで十分です。

以下の手順は、https://pip.pypa.io/en/stable/user_guide/#installing-from-local-packages から引用されたものです

インターネット接続環境でビルドし、その後、以下の手順でインストールします:

# Remove any locally cached (previously built) wheels.
pip cache remove gmxapi

# Download gmxapi and dependencies from pypi.
pip wheel --wheel-dir DIR gmxapi
# or, using package source from the GROMACS repository
cd python_packaging/gmxapi
pip wheel --wheel-dir DIR .

# Later, install.
pip install --no-index --find-links=DIR DIR/gmxapi*whl

後でビルドおよびインストールするために、パッケージと依存関係をダウンロードするには：

# if in the GROMACS source repository
cd python_packaging/gmxapi
# or download and expand the archive
pip download --destination-directory DIR gmxapi
tar xf DIR/gmxapi*
cd gmxapi*

# Pre-fetch dependencies to DIR
pip download --destination-directory DIR .

# Build and install from the source directory.
pip install --no-index --find-links=DIR .

ソースアーカイブの作成

gmxapi Python パッケージ Python パッケージのソースアーカイブは、Python の build モジュールを使用して、GROMACS のソースリポジトリから作成できます。詳細は、[pypa-build のドキュメント](https://pypa-build.readthedocs.io/en/latest/)を参照してください。

例:

pip install --upgrade setuptools build
cd python_packaging/gmxapi
python -m build --sdist

このコマンドは、ソース配布アーカイブファイルを含む dist ディレクトリを作成します。 ファイル名は、 gmxapi-version.suffix の形式で、version はパッケージメタデータのバージョンを表し、suffix はローカル環境と現在のパッケージング仕様によって決定されるアーカイブファイル拡張子を表します。

バージョン情報は、gmxapi.__version__ で定義されている gmxapi.version モジュールによって取得されます。 Issue 3851 での修正が完了するまでは、gmxapi のバージョン情報は version.py にハードコードされています。 新しいリリースを配布する前に、ソースの最新版を使用し、バージョン情報が適切であることを確認してください。

参考

Python documentation for creating a source distribution

パッケージの管理者の方は、オンラインリポジトリ <https://pypi.org/project/gmxapi/>`__を、`python -m twine upload dist/gmxapi-{version}.{suffix}`を使用して、最新にビルドされた ``sdist` をアップロードすることで更新できます。PyPIテストサーバーのリポジトリを更新するには、`python -m twine upload --repository testpypi dist/gmxapi-{version}.{suffix}`を使用します。

gmxapiドキュメントへのアクセス

gmx モジュールの Python クラスと関数のドキュメントは、通常の方法でアクセスできます。コマンドラインから pydoc を使用するか、インタラクティブな Python セッションで help() を使用します。

このドキュメント（現在お読みになっているもの）は、オンライン で閲覧するか、GROMACS ソースリポジトリのコピーから構築できます。

ドキュメントは、Python モジュールのドキュメントと静的なコンテンツの組み合わせで構成されており、GROMACS のソースリポジトリのローカルコピーが必要です。

GROMACS を使用して構築

GROMACS を使用して、完全な gmxapi ドキュメントを構築するには、GROMACS を -DGMX_PYTHON_PACKAGE=ON で構成し、通常の手順で GROMACS のドキュメントを構築します。これにより、まず gmxapi Python パッケージがビルドツリー内の一時的な場所にビルドされ、インストールされます。その後、Sphinx はパッケージを自動的にインポートして、Python のドキュメント文字列を抽出できます。

注意：このインストールは完全にCMakeによって制御されており、Pythonの依存関係は自動的にインストールされません。CMakeを設定する前に、リポジトリ内の`python_packaging/`ディレクトリにある`requirements.txt`ファイルを使用して、Python環境を更新できます。例:

pip install -r python_packaging/gmxapi/requirements.txt

場合によっては、ビルド環境が、あなたが意図したPythonインタプリタとは異なるものを選択することがあります。 Python3_ROOT_DIR または CMAKE_PREFIX_PATH のCMake変数を設定することで、明示的にPythonのインストールまたは venv ディレクトリを選択できます。 また、CMake FindPython3 を参照してください。

もし、pyenv または pyenv-virtualenv を使用して Python のバージョンを動的に管理している場合、pyenv version-name コマンドとディレクトリを pyenv prefix {version} で指定することで、特定のバージョンを特定できます。たとえば:

-DPython3_ROOT_DIR=$(pyenv prefix $(pyenv version-name))

テスト

注: 上記の「テスト要件」を確認してください。

gmxapi Python パッケージをインストールした後、GROMACS のソースツリーから Python テストスイートを実行できます。 例:

# Assuming you are in the root directory of the repository:
pytest python_packaging/gmxapi/test/

詳細については、python_packaging/README.md を参照してください。

トラブルシューティング

実行時に動的リンクエラーが発生し、ImportErrorが発生

症状: Pythonで``ImportError`` が発生し、原因として dlopen などが示される:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: dlopen(/.../gmxapi/_gmxapi.so, 0x0002): Symbol not found:
__ZN12gmxapicompat11readTprFileERKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEE
  Referenced from: /.../gmxapi/_gmxapi.so
  Expected in: /path/to/gromacs/lib/libgmxapi_mpi_d.0.3.1.dylib

ビルドおよび実行環境の不一致は、実行時に動的リンクの問題を引き起こす可能性があります。これは、|Gromacs|を異なるコンパイラで再構築した場合、または``pip``または``CMake``が誤ったコンパイラツールチェーンを使用するように「騙された」場合に発生する可能性があります。

「gmxapi cmake に関するヒント」_ を参照して、コンパイラツールの情報をご確認ください。 --no-cache-dir オプションを使用して、gmxapi Python パッケージを再構築し、再インストールし、使用する GROMACS のインストールに必要な gromacs-hints.cmake ファイルを提供してください。

エラー: モジュール 'enum' に 'IntFlag' という属性がありません。

もし、依存関係のいくつかのバージョンが古い場合、enum34 パッケージへの転移的な依存関係が発生する可能性があります。 以下のコマンドを試してください:

pip uninstall -y enum34

そして、それが問題を解決するかどうかを確認してください。解決しない場合は、問題を特定するために、新しい仮想環境 (上記を参照) を試してください。問題を特定するために、問題を報告する してください。

pybind11 に関するエラー

setup.py でエラーが発生し、出力に以下のような内容が含まれる場合があります:

  ModuleNotFoundError: No module named 'pybind11'
  Building wheel for gmxapi (pyproject.toml): finished with status 'error'
  ERROR: Failed building wheel for gmxapi
Failed to build gmxapi
ERROR: Could not build wheels for gmxapi, which is required to install pyproject.toml-based projects

ここに記載されている重要な情報は、「pybind11」が見つからないことです。

ビルドに必要な依存関係は、必ずしも自動的にインストールされるわけではありません。pip`を使用している場合でも、--no-build-isolation`や`--no-deps`のようなオプションで、依存関係の自動インストールを無効にしている可能性があります。

いずれの場合でも、問題は``pybind11``Pythonパッケージを明示的にインストールしてから、``gmxapi``をビルドすることで解決されるはずです:

pip install --upgrade pybind11

gmxapi サポートライブラリが見つかりませんでしたか？

もし、:ref:`GMXRC ファイルを「ソース」する必要がない場合は、gmxapi_ROOT``を使用して、gmxapi と互換性のある |Gromacs| インストール場所を指定できます。 たとえば、``gmxapi_ROOT=/path/to/gromacs pip install . のように使用します。

gmxapi パッケージを更新する前に、通常は以前のインストールを削除し、新しいビルドディレクトリから始めることが推奨されます。 pip uninstall gmxapi を実行できるはずです。

以下の様なものが見えますか？

CMake Error at gmx/core/CMakeLists.txt:45 (find_package):
   Could not find a package configuration file provided by "gmxapi" with any
   of the following names:

     gmxapiConfig.cmake
     gmxapi-config.cmake

   Add the installation prefix of "gmxapi" to CMAKE_PREFIX_PATH or set
   "gmxapi_ROOT" to a directory containing one of the above files.  If "gmxapi"
   provides a separate development package or SDK, be sure it has been
   installed.

これは、以下の理由による可能性があります

  • GROMACS はまだインストールされていません

  • GROMACS は、CMake 変数 GMXAPI=ON を使用せずに構築されました

  • または、gmxapi_ROOT``（または``GROMACS_DIR）が、``bin``や``share``のようなディレクトリを含むパスでない場合。

もし、ご自身がシステム管理者でない場合は、virtualenv`または`Conda`を使用して作成したPython仮想環境にインストールすることをお勧めします。そうでない場合、`pip`に--user`フラグを指定する必要があります。

最も一般的な問題は、互換性のないコンパイラとPythonです。Gromacs、Pythonパッケージ、およびサンプルプラグインに対して、同じCおよびC++コンパイラを使用するようにしてください。これらのコンパイラは、`mpi4py`のコンパイルに使用される：`mpicc`コンパイララッパーと対応している必要があります（詳細は：<https://mpi4py.readthedocs.io/en/stable/install.html>）。Pythonパッケージを構築するには、Pythonヘッダーまたは開発環境のインストールが必要です。これらのインストールが、使用しているマシンにすでにインストールされているとは限りません。 (インストールされていない場合は、Python.hが見つからないというエラーが発生します。) 複数のPython環境（またはHPCシステムで利用可能なモジュール）がある場合は、他のPython環境を試すか、またはシステム管理者として適切なPython開発パッケージをインストールできます。あるいは、AnacondaまたはMiniCondaをホームディレクトリにインストールすることもできます。

CMakeで「gmxapi」が見つからないというエラーでインストールが失敗した場合、「Gromacs」がインストールされ、インストール時に認識されていることを確認してください。たとえば、

gmxapi_ROOT=/Users/eric/gromacs pip install --verbose gmxapi

pip`および関連するPythonのパッケージ管理ツールは、場合によっては柔軟すぎたり、曖昧すぎたりすることがあります。もし状況が非常に悪化した場合、明示的に:py:mod:``gmxapi`モジュールとその依存関係をアンインストールし、再度実行して、`:command:``pip``がどのパッケージのバージョンも見つけられなくなるまで繰り返してください。

pip uninstall gmxapi
pip uninstall cmake
# ...

テストスイートを正常に実行することは、機能する gmxapi パッケージを持っていることには必須ではありません。テストの堅牢性を高めるための取り組みを行っていますが、現状ではテストスイートはやや不安定で、正常に gmxapi パッケージを構築した場合でも、正しく動作しない可能性があります。問題のトラブルシューティングを行う場合は、自動的に必要な Python パッケージをインストールできない（手動でのインストールが必要、例：pip install somepackage）こと、および Python のバージョン間の曖昧さが主な原因であると考えられます。

もし、リポジトリの開発ブランチで作業している場合は、新しいリリースがタグ付けされた後に、上流ブランチが「main」にリセットされる可能性があることに注意してください。一般的には、特に「devel」ブランチでは、git pull`を実行する際には、--rebase`フラグを使用する必要があります。

もし、このリポジトリをクローンし、その結果として次のgitステータスが表示された場合:

$ git status
On branch devel
Your branch and 'origin/devel' have diverged,
and have 31 and 29 different commits each, respectively.

その後、:py:mod:`gmxapi`は新しい開発サイクルに入った可能性があります。最新の開発ブランチに更新するには、:command:`git pull --rebase`を実行してください。

もし、``devel``環境で`:command:git pull`を実行した際に、予期せぬマージ競合が発生した場合、「:command:`git merge --abort; git pull --rebase」を実行することで、正常な状態に戻ることができます。

gmxapi用のコードを開発している場合は、これは新しい開発サイクルに合わせて、機能ブランチをリベースする必要があることを示しています。