The pARTn API
Description
The API can be used to interact with, or fully control the pARTn from another application.
To interact with the memory of pARTn, the artn_set and artn_extract functions are used, see this page.
All API functions are written in fortran, and have an equivalent C-function. To use the API in python, an interface module is needed.
In the directory artn-plugin/interface there is the C-header file artn.h, and the python interface module pypARTn.
Examples
Some simple examples of calling the pARTn API from different languages are in the examples/COUPLE directory.
Usage
The general idea is to first use the artn_create function, which is documented below.
After that, the ARTn memory can be handled externally.
- group group_artn_create
Functions
- integer function, public artn_create ()
Prepare pARTn to be called through the API: set some variables to avoid reading/writing to files.
This is not strictly needed to execute, but take care when omitting it.
Example:
use artn_api, only: artn_create integer :: ierr ierr = artn_create()
C-wrapper:
#include artn.h int ierr = artn_create()
Usage from fortran
To use the API from fortran, you need to use the artn_api module in you code. In order to do that, your source code must be compiled with including the pARTn object files, and linked with libartn.so. For example a caller source file named my_code.f90 could be:
use artn_api
implicit none
integer :: ierr
ierr = artn_create()
call artn_set( "engine_units", "lammps/metal" )
call artn_set( "forc_thr", 1e-3 )
! ... etc
To compile this with gfortran, include the src/Obj directory of pARTn with the -I option, and link the -lartn library (libartn.so):
ARTN_PATH=/your/path/to/pARTn
ARTN_LIB= -L$(ARTN_PATH)/lib -lartn
gfortran -I$(ARTN_PATH)/src/Obj -o my_code.x my_code.f90 $(ARTN_LIB) -Wl,-rpath,$(ARTN_PATH)/lib
The -Wl,-rpath, part is to specify the runtime path to find the libartn.so.
Note
If the caller my_code.f90 will use lammps as the engine, then you should link with -lartn-lmp (libartn-lmp.so) instead.
Usage from C
Under construction, see “Usage from fortran” in the meantime, should be similar if not identical for C.
Usage from python
The python interface is the module pypARTn, defined in the directory artn-plugin/interface.
In order to use it, build pARTn with pip, or specify the path in the PYTHONPATH environment variable:
export PYTHONPATH=/your/path/to/artn-plugin/interface:$PYTHONPATH
Then import, and initialize the module with the engine keyword:
>>> import pypARTn
>>> artn = pypARTn.artn( engine = "other" )
The engine keyword currently accepts values lammps and other. When using lammps as the engine, use the according keyword.