パブリック C++ API

概要

軌道解析ツールおよびプラグ可能なMD拡張機能（例：`sample_restraint <https://gitlab.com/gromacs/gromacs/-/tree/main/python_packaging/sample_restraint>`に基づいたコードを使用するもの）は、``libgromacs``によってサポートされている：file:`gromacs/`ヘッダーを使用します。

詳細については、libgromacs およびインストールされている gromacs/ ヘッダーの使用方法については、Legacy API のドキュメントを参照してください。

また、「Trajectory Analysis Framework <../doxygen/html-user/page_analysisframework.xhtml>」も参照してください。

新しいパブリックAPI機能（例：gmxapi）を使用するソフトウェアは、CMakeと``find_package(gmxapi)``を使用して、gmxapi/`ヘッダーを使用し、`::gmxapi`` C++名前空間をサポートするライブラリへのリンクを含むビルドシステムを設定します。

現在、「gmxapi」ライブラリは「libgromacs」への間接的な依存関係を持っています。`CMake 3.24.0`のバグ（<https://gitlab.kitware.com/cmake/cmake/-/issues/23838>）により、「find_package(gmxapi)」は、クライアントソフトウェアが通常、「cmake」::`Gromacs::libgromacs`またはその詳細を明示的に使用する必要がないにもかかわらず、誤ったエラーを回避するために、「find_package(gromacs${GROMACS_SUFFIX})」を暗黙的に呼び出す必要があります。

クライアント向けビルドシステムサポート

GROMACS は、ビルドシステムを構成および管理するために、CMake を強く依存しています。 GROMACS のインストールは、$GROMACS_ROOT/share/cmake/ にインストールされた設定ファイルと「ヒント」ファイルを通じて、CMake で構成されたクライアントソフトウェアを直接サポートします。

gmx --version (または適切な gmx$GROMACS_SUFFIX) には、元のビルドツールチェーンに関する情報が含まれており、これはクライアントソフトウェアのビルドシステムを構成するために、必ずしも十分ではない場合があります。

コンパイラツールチェーン

ただし、明示的には必要ではありませんが、GROMACS のビルドに使用されているツールチェーンと一致するようにクライアントソフトウェアをビルドすることが強く推奨されます。これにより、バイナリ互換性の問題を回避できます。

各 GROMACS インストール（2022年以降）には、CMake の「ヒント」ファイルが含まれており、これを使用して cmake のキャッシュを -C オプション https://cmake.org/cmake/help/v3.24/manual/cmake.1.html#options を使用して初期化できます。

Gromacsのインストールが $GROMACS_ROOT/`にある場合、特定の :cmake:`GROMACS_SUFFIX`に対応するヒントファイルは、次の場所にあります： :file:`$GROMACS_ROOT/share/cmake/gromacs$GROMACS_SUFFIX/gromacs-hints$GROMACS_SUFFIX.cmake

ヒントファイルは、find_package(gmxapi) および find_package(GROMACS) をサポートする CMake 設定ファイルとは完全に独立しています。

ただし、クライアントの`:command:cmake`構成コマンドラインで `-C path/to/gromacs-hints$GROMACS_SUFFIX.cmake`` を使用することで、適切なコンパイラオプションを設定し、互換性のあるバイナリを構築する可能性を高めることができます。（つまり、:func:`gromacs_check_compiler が正常に実行されるのを支援します。）

CMake 用のヒント変数である enable_language と find_package 以外に、クライアントのビルドシステムが GROMACS インストールの構築に使用された CMake のバージョンを知る必要がある場合に、ヒントファイルに GMX_CMAKE_VERSION を設定します。

MPIサポート

GROMACS は、FindMPI (CMake の find_package(MPI ...) をサポートするモジュール) を使用して、MPI のサポートに必要なコンパイラとリンカのオプションを特定し、設定します。 クライアントソフトウェアも同様の手続きを行うことを推奨します。

もし、Gromacsがビルド時にMPIのサポートを検出した場合、*gromacs-hints*ファイル（上記を参照）には、``find_package``が同じMPIインスタンスを見つけるのに役立つ入力変数が定義されます。

注意点

GROMACS が、別の環境で構築されたパッケージからインストールされた場合、組み込みツールチェーンの情報が不正確になる可能性があります。これにより、gmx --version の出力が誤りになったり、gromacs-hints ファイルが無効になったりする可能性があります。クライアントのビルドシステムを設定する際に、誤った警告が表示されることがあります。また、クライアントソフトウェアが GROMACS のインストールと適切に連携するかどうかは、状況によって異なります。

複数のツールチェーンが利用可能なコンピューティング環境（例えば、一般的な高性能コンピューティング（HPC）クラスタ）では、ツールチェーンは一貫した動作のために環境変数に依存する場合があります。 GROMACS のビルド環境を設定する際に、例えば :command: module load gcc openmpi/gcc のように環境モジュールを使用した場合、クライアントソフトウェアをビルドする前に、同じ環境モジュールをロードする必要がある場合があります。

gmxapi CMake パッケージ

|Gromacs|にインストールされたCMake構成ファイルは、CMakeの「構成モード」をサポートしています。これは、find_package のCMakeコマンドを使用するためです。gromacs$GROMACS_SUFFIX パッケージとは異なり、CMake構成ファイルは、単一の「gmxapi」パッケージ名のみをサポートします。

gmxapi API と ABI は、異なるビルドオプションから libgromacs に存在するほとんどの差異を隠蔽します。ただし、gmxapi/mpi/resourceassignment.h インターフェースは、元の GMX_MPI の選択によって影響を受けます。 MPI を有効にしたクライアントソフトウェア向けには、gmxapi/mpi/gmxapi_mpi.h テンプレートヘッダーを通じて、安定したインターフェースが提供されています。

一部の GROMACS インストールには、複数のビルドが含まれています。たとえば、:file:`libgromacs.so、:file:`libgromacs_d.so、:file:`libgromacs_mpi.so、および :file:`libgromacs_mpi_d.so が含まれている場合があります（:cmake:`GMX_DOUBLE および :cmake:`GMX_MPI のビルド時の値に応じて）。いずれか 1つ が Gromacs::libgromacs CMake ターゲットによって提供される可能性があります。 :issue:`4334 の解決されるまで、1つの Gromacs::gmxapi のバージョンのみが GROMACS インストールからインポート可能です。 各 GROMACS インストール（:cmake:`GMXAPI を ``ON` に設定）は、以前にインストールされた gmxapi サポートの CMake 設定ファイルを上書きします。

インポートされたターゲット

Gromacs::gmxapi

gmxapi パッケージは、インストールされている gmxapi/ ヘッダーへのアクセスを提供する単一の Gromacs::gmxapi ターゲットを提供します。関連する共有オブジェクトライブラリの名前は、ビルドシステムの設定オプションによって異なります ( GMX_DOUBLE および GMX_MPI を参照)。

gromacs (および gromacs$GROMACS_SUFFIX パッケージ)

find_package(GROMACS) をサポートするための CMake 関連機能には、2 つの要素があります。 1. FindGROMACS.cmake という名前の検索モジュール（インストールディレクトリの share/gromacs/template/cmake/ に、およびソースツリーの share/template/cmake/ にあります）。 2. 実際のパッケージ構成ファイル（gromacs-config.cmake および、src/gromacs/ 内の入力ファイルから share/cmake/ にインストールされたサポートファイル）。

FindGROMACS.cmake は、パッケージ構成ファイルに対するシンプルなラッパーであり、同じインストールプレフィックスで複数のサフィックス付きの GROMACS インストールをサポートする仕組みへの、より便利なインターフェースを提供します（詳細は以下の GROMACS_SUFFIX 変数をご参照ください）。このファイルはバージョン非依存で、主要な GROMACS リリースの間でも、前向きおよび逆向きの両方で互換性を維持するように設計されています。すべてのバージョン固有の情報と、コンパイルおよびリンク設定に関する実際の詳細は、パッケージ構成ファイルに記載されています。 FindGROMACS.cmake を利用するビルドシステムは、ローカルコピーを作成し、インストールされている share/gromacs/template/CMakeLists.txt で使用されているのと同じように使用できます。必要に応じて、パッケージ構成ファイルも直接使用し、FindGROMACS.cmake をバイパスすることも可能です。

FindGROMACS.cmake``を使用する場合、``find_package(GROMACS) は gromacs、gromacs_d、gromacs_mpi、または gromacs_mpi_d のいずれかの CMake パッケージの構成を見つけることができます。そうでない場合は、探している正確なパッケージ名を指定する必要があります。例：find_package(gromacs_d)。

インポートされたターゲット

Gromacs::libgromacs

提供：インストールされたコア GROMACS ライブラリと：file:gromacs/ ヘッダーへのアクセス：「target_link_libraries(foo PRIVATE Gromacs::libgromacs)」

Gromacs::gmx

コマンドライン実行可能ファイルを表します。たとえば、ローカルの CMake 変数 _gmx_executable を実行可能ファイルのパス（正しい GROMACS_SUFFIX を含む）に設定するには、get_target_property(_gmx_executable Gromacs::gmx LOCATION) を CMakeLists.txt で使用できます。

入力オプション

入力オプション：検索対象を制御するための設定

GROMACS_SUFFIX

(「FindGROMACS.cmake」のみ)

この CMake 変数は、find_package(GROMACS) を呼び出す前に設定することで、検索する GROMACS のサフィックスを指定できます。 設定しない場合、サフィックスのないバージョンが検索されます。 パッケージ構成ファイルを使用する場合は、find_package(GROMACS NAMES gromacs<suffix>) を使用してサフィックスを設定する必要があります。

GROMACS_PREFER_STATIC

この CMake 変数は、find_package(GROMACS) を呼び出す前に設定することで、静的ライブラリと共有ライブラリのどちらを優先するかを指定できます。これは、どの GROMACS インストールを選択するかには影響しませんが、そのインストールに静的および共有ライブラリの両方が利用可能（同じサフィックスを持つ 2 つの異なるビルドからインストールされた場合）の場合、この変数は GROMACS_LIBRARIES に返されるライブラリを選択します。

GROMACS_DIR

この CMake (キャッシュ) 変数は、find_package によって提供される標準的なメカニズムであり、GROMACS の検索場所を示すヒントを指定するために使用できます。また、CMAKE_PREFIX_PATH もこの目的で使用できます。詳細は、CMake の find_package に関するドキュメントを参照してください。GROMACS_DIR は環境変数として設定することもでき、これは GMXRC によって行われます。

出力変数

出力変数で、見つかった libgromacs とヘッダーの使用方法を指定します。

GROMACS_INCLUDE_DIRS

|Gromacs|ヘッダーとのコンパイルに必要なインクルードディレクトリのリスト。現在、これには|Gromacs|ヘッダーへのパスが含まれています。

GROMACS_LIBRARIES

GROMACS とリンクするためにリンクするライブラリのリスト。内部的には、この機能は、libgromacs を表すためにインポートされた CMake ターゲットを使用します。

GROMACS_DEFINITIONS

GROMACS ヘッダーをコンパイルするために必要なコンパイル定義（-D プレフィックス付き）のリスト。

GROMACS_IS_DOUBLE

GROMACS がダブル精度でコンパイルされたかどうか。

GROMACS_CXX_FLAGS

必要なコンパイラオプション。

マクロ/関数

設定の正当性を確認するために使用できる、宣言されたマクロ/関数:

gromacs_check_double(GMX_DOUBLE)

確認します。見つかった GROMACS が、期待される精度であることを確認します。パラメータ GMX_DOUBLE は、ダブル精度が要求されたかどうかを指定するキャッシュ変数の名前である必要があります。

gromacs_check_compiler(LANG)

確認します。見つかった GROMACS が、現在の CMake システムで使用されているコンパイラと同じコンパイラでコンパイルされていることを。 現在、「LANG=CXX」のみがサポートされています。