prips 1.4

Description:

prips 1.4

PRIPS: Python Runtime Interface Plugin of SPONGE
SPONGE的python的运行时接口插件
该插件将SPONGE视为一个python解释器，运行python脚本
依赖
该插件依赖于cupy。请自行安装好适配你CUDA版本的cupy。
为什么需要cupy？
SPONGE的GPU代码需要适配GPU的python端的库，许多库都能满足，如cupy、jax、torch以及mindspore。而cupy是上述里唯一一个支持“野”指针的库，也即cupy.cuda.UnownedMemory，使得它能直接调用SPONGE的内存地址作为自变量，而不需要显式地同步。另外cupy作为一个中介，它的数组也可以比较方便地转化为其他库的数组。
安装
安装方法：

pypi安装

pip install prips


本地安装
前往gitee库下载解压或克隆源码

git clone https://gitee.com/gao_hyp_xyj_admin/sponge_pyplugin.git

打开下载并解压或克隆后的文件夹，在有pyproject.py的文件夹内呼出合适的shell终端，如windows下的powershell或linux下的shell
pip install .

使用
SPONGE命令
目前本插件适用的版本为：1.4，也即SPONGE的1.4正式版本
首先在命令行中输入：
python -c "import prips"

然后正常情况下会输出
PRIPS: Python Runtime Interface Plugin of SPONGE

Version: 1.4a0
Path: xxx\prips\_prips.so

Usage:
1. Copy the path printed above
2. Paste it to the value of the command "plugin" of SPONGE

在SPONGE的mdin.txt文件夹中加入：
plugin = xxx\prips\_prips.so #上方的Path
py = xxxx\example.py #你需要使用的python脚本地址

此处的 xxxx\example.py仅为示例，请修改为你对应的地址。
SPONGE获取python信息
SPONGE读取python信息使用的方式是读取函数名。
首先，SPONGE会直接逐行运行一遍该python脚本，由此可进行初始化。
然后，SPONGE会读取python脚本里的After_Initial()、Calculate_Force()和Mdout_Print()，分别在其他模块初始完毕、力计算和打印信息的时候调用。例如下面是一个简单的Example.py
def Mdout_Print():
print("Hellow SPONGE World!")

python获取SPONGE信息
python由模块Sponge获取SPONGE信息。模块Sponge是SPONGE作为解释器时的内置模块，在外部用python调用是没有的。
Sponge模块内若干个子模块，其中controller（程序控制）、cv_controller（CV定义）、md_info（MD信息）是较为重要的模块。这些子模块的定义与C++版本的定义相同。可以使用help()寻求帮助，或阅读下面的API介绍。
import Sponge
help(Sponge.controller)
help(Sponge.cv_controller)
help(Sponge.md_info)

简单例子
以下是一个简单的steer MD的例子，对第一个原子的y方向加上一个力。
import Sponge
my_force_factor = 1
if Sponge.controller.Command_Exist("my_force_factor"):
my_force_factor = float(Sponge.controller.Command("my_force_factor"))
Sponge.controller.Step_Print_Initial("My_Force_Potential", "%2f")

def Calculate_Force():
Sponge.md_info.frc[0][1] += my_force_factor

def Mdout_Print():
Sponge.controller.Step_Print("My_Force_Potential", -my_force_factor * Sponge.md_info.crd[0][1])

API介绍


Sponge


Sponge.spongeError


Sponge.COLLECTIVE_VARIABLE_NEED


Sponge.controller


Sponge.cv_controller


Sponge.md_info

Sponge.md_info.sys



Sponge.NEIGHBOR_LIST




Sponge
Help on built-in module Sponge:

NAME
Sponge

DATA
controller = < IO and CUDA controller of SPONGE >
cv_controller = < cv controller of SPONGE>
fname = r'D:\prips\api_generator.py'
md_info = < MD information container of SPONGE >

FILE
(built-in)



Sponge.spongeError
Sponge.spongeError.spongeSuccess = 0
Sponge.spongeError.spongeErrorNotImplemented = 1001
Sponge.spongeError.spongeErrorBadFileFormat = 1002
Sponge.spongeError.spongeErrorConflictingCommand = 1003
Sponge.spongeError.spongeErrorMissingCommand = 1004
Sponge.spongeError.spongeErrorTypeErrorCommand = 1005
Sponge.spongeError.spongeErrorValueErrorCommand = 1006
Sponge.spongeError.spongeErrorSimulationBreakDown = 1007
Sponge.spongeError.spongeErrorMallocFailed = 1008
Sponge.spongeError.spongeErrorOverflow = 1009
Sponge.spongeError.spongeErrorOpenFileFailed = 1010


Sponge.COLLECTIVE_VARIABLE_NEED
Sponge.COLLECTIVE_VARIABLE_NEED.CV_NEED_GPU_VALUE = 1
Sponge.COLLECTIVE_VARIABLE_NEED.CV_NEED_CRD_GRADS = 2
Sponge.COLLECTIVE_VARIABLE_NEED.CV_NEED_CPU_VALUE = 4
Sponge.COLLECTIVE_VARIABLE_NEED.CV_NEED_BOX_GRADS = 8


Sponge.controller
Help on CONTROLLER in module __main__ object:

class CONTROLLER(builtins.object)
| this **class** is the module to control the input, output and cuda in SPONGE
|
| Methods defined here:
|
| Command(self, arg1, arg2=None)
| Get the simplified value of the command in SPONGE.
| If Only arg1 is given, the command to get the value is "arg1".
| If arg1 and arg2 is given, the command to get the value is "arg1_arg2".
|
| :param arg1: the command or the command prefix
| :param arg2: the command suffix
| :return: a string, the simplified value of the command
|
| Command_Exist(self, arg1, arg2=None)
| Check the command whether exist in SPONGE.
| If Only arg1 is given, the command to check is "arg1".
| If arg1 and arg2 is given, the command to check is "arg1_arg2".
|
| :param arg1: the command or the command prefix
| :param arg2: the command suffix
| :return: True if the command exist, else False
|
| Original_Command(self, arg1, arg2=None)
| Get the original value of the command in SPONGE.
| If Only arg1 is given, the command to get the value is "arg1".
| If arg1 and arg2 is given, the command to get the value is "arg1_arg2".
|
| :param arg1: the command or the command prefix
| :param arg2: the command suffix
| :return: a string, the original value of the command
|
| Step_Print(self, head, content)
| Print a step print item. A step print item is an item to print in the screen and in the mdout file.
|
| :param head: the name of the item
| :param content: the content of the step print item
|
| Step_Print_Initial(self, head, format)
| Initialize a step print item. A step print item is an item to print in the screen and in the mdout file.
|
| :param head: the name of the item
| :param format: the format of the step print item
|
| Throw_SPONGE_Error(self, error, error_by, error_hint)
| Raise error to the screen and the mdinfo file, then exit
|
| Warn(self, warning)
| Print the warning to the screen and the mdinfo file
|
| __init__(self)
|
| __repr__(self)
|
| printf(self, *values, sep=' ', end='\n')
| Print the values to the screen and the mdinfo file
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| working_device
| The working device id
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)


Sponge.cv_controller
Help on COLLECTIVE_VARIABLE_CONTROLLER in module __main__ object:

class COLLECTIVE_VARIABLE_CONTROLLER(CONTROLLER)
| Method resolution order:
| COLLECTIVE_VARIABLE_CONTROLLER
| CONTROLLER
| builtins.object
|
| Methods defined here:
|
| Ask_For_CV(self, name, N, verbose_level=0)
|
| Command(self, arg1, arg2=None)
|
| Command_Exist(self, arg1, arg2=None)
|
| Get_CV(self, cv_name)
|
| Original_Command(self, arg1, arg2=None)
|
| __repr__(self)
|
| ----------------------------------------------------------------------
| Methods inherited from CONTROLLER:
|
| Step_Print(self, head, content)
| Print a step print item. A step print item is an item to print in the screen and in the mdout file.
|
| :param head: the name of the item
| :param content: the content of the step print item
|
| Step_Print_Initial(self, head, format)
| Initialize a step print item. A step print item is an item to print in the screen and in the mdout file.
|
| :param head: the name of the item
| :param format: the format of the step print item
|
| Throw_SPONGE_Error(self, error, error_by, error_hint)
| Raise error to the screen and the mdinfo file, then exit
|
| Warn(self, warning)
| Print the warning to the screen and the mdinfo file
|
| __init__(self)
|
| printf(self, *values, sep=' ', end='\n')
| Print the values to the screen and the mdinfo file
|
| ----------------------------------------------------------------------
| Readonly properties inherited from CONTROLLER:
|
| working_device
| The working device id
|
| ----------------------------------------------------------------------
| Data descriptors inherited from CONTROLLER:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)


Sponge.md_info
Help on MD_INFORMATION in module __main__ object:

class MD_INFORMATION(builtins.object)
| Contains the information for MD simulations
|
| Methods defined here:
|
| __init__(self)
|
| __repr__(self)
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| atom_numbers
| the total number of atoms
|
| d_mass
| the mass of the atoms
|
| sys
| the system information
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| crd
| the position coordinates of the atoms
|
| d_atom_energy
| the energy of the atoms
|
| d_atom_virial
| the virial of the atoms
|
| d_charge
| the charge of the atoms (In the unit of SPONGE, a unit charge is 18.2223)
|
| frc
| the force of the atoms
|
| vel
| the velocity of the atoms


Sponge.md_info.sys
Help on system_information in module __main__ object:

class system_information(builtins.object)
| the system information of MD information
|
| Readonly properties defined here:
|
| box_length
| the length of the box
|
| steps
| the current step of the simulation
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)


Sponge.NEIGHBOR_LIST
Help on class NEIGHBOR_LIST in module __main__:

class NEIGHBOR_LIST(builtins.object)
| Neighbor List of SPONGE.
| This class should be initialized at After_Initial, because neighbor_list is not initialized when initializing prips
|
| Methods defined here:
|
| __init__(self)
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| atom_numbers
| the number of neighbors for every atom
|
| atom_serials
| the serial of neighbors for every atom
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)