about
Manual
BioPfuga
libwrapper: Libraries to exchange data in BioPfuga
libwrapper is a group of libraries to exchange data between slave programs (i) in MPI-2 master-slave type program, and (ii) by using files described by XML format, UDS-XML.


libwrapper supports the data exchange between 2 processes. It also compares the unit system at the time of receiving data and when necessary it does unit conversion.
Currently libwrapper supports unit system such as au and KCAL/MOL. It can deal with 4 kinds of data including coordinate, charge, energy and force.
libwrapper can not handle any unit system and data besides those. So, in order to deal with others libwrapper program needs to be modified.


In libwrapper there are 2 ways for exchanging data between slave programs.
(1)MPI mode
Data is exchanged by MPI communication. MPI communication is executed via master program.


(2)UDSXML mode
Data is exchanged by using file. This file is generated in XML format.
Also, the start of reading file is controlled by synchronous message passing from parent process.





1. Compile method
Depending on the environment, please change the description below in configure.ac.
1) Execution of configure
Depending on UDSXML environment, please execute as follows:

./configure --with-udsxml-incdir=/usr/local/libudsxml-3.0/src ¥
    --with-xercesc-incdir=$HOME/xerces-c1_6_0-linux/include ¥
    --with-xercesc-libdir=$HOME/xerces-c1_6_0-linux/lib ¥
    --with-xercesc-libname=libxerces-c1_6_0.so


o with-udsxml-incdir Include path for UDSXML
o with-xercesc-incdir Include path for XML parser(Apache Xerces-C)
o with-xercesc-libdir Library path for XML parser(Apache Xerces-C)
o with-xercesc-libname Library file name for XML parser(Apache Xerces-C)

Edit attached runConfigure and execute, then same functionality can be achiev
2) make


2. Loading from application
2.1. Integration into program
Since libwrapper can be used only in master- slave type program using spawn function of MPI-2, the program needs to be modified to master-slave type program as shown below:
(1)Master program

    (1-1)Add initialization process of MPI-2
    (1-2)Add spawn process of slave program
    (1-3)Add process of specifying communication mode to slave program
    (1-4)Add process of controlling data exchange between slave programs
    (1-5)Add termination process of MPI-2



(2)Slave program
    (2-1) Add initialization process of MPI-2
    (2-2) Receive communication mode from master and add process of setting communication mode.
    (2-3)Add communication process between slave programs.
    (2-4)Add termination process of MPI-2


There is an example program in sample directory.
(a)Program before master-slaved
    (a-1)original.f : Program that shows average position of coordinates in au unit system from one water molecule set in KCAL/MOL unit system.


(b)Program after master-slaved
    (b-1)master.f : master program (b-2)create_slave.f : slave program which creates water molecule in KCAL/MOL unit system. (b-3)median_slave.f : program which calculates average position from input coordinates

    Depending on compiler of ＃ vendor, "_" need to be added to the end of each procedure name of wrapper.


2.2. Link
    Please link libudsxml.a, libxerces-cXXXX.so and libwrapper.a from application.
    mpi library need to be liked as well.
2.3. Execution
    Execute master process in mpirun command.
    Please refer to the following command in sample directory.

    runMPI : Program execution in data passing using MPI (LAMMPI version)
    runUDS : Program execution in data passing using UDSXML (LAMMPI version)


3. Specification
3.1. bp_set_mode
Since libwrapper can be used only in master- slave type program using spawn function of MPI-2, the program needs to be modified to master-slave type program as shown below:

[Feature] Specify data exchange method between programs
[Function definition]
void set_mode(
char *mode, /* data exchange method(input) */
char *parts) /* program identifier (input) */
subroutine set_mode(mode, parts)
character(*) mode, parts
[Return value] none
[Details] Specify method for exchanging data between programs mode: "mpi " or "uds " can be specified.
Parts: identifier can be set for the program.In case, error occur while exchanging data, the program identifier is outputted.


3-2. bp_send_message_to_parent
[Feature] Send character string to parent process.
[Function definition]
void bp_send_message_to_parent(
char *message) /* transmission message (input)
subroutine bp_send_message_to_parent(
character(*) message)
[Return value] none
[Details] For character string of message, the following 4 kinds can be used.
"post" : synchronization
"stop" : process termination
"mpi " : mpi mode
"uds " : udsxml mode


3-3. bp_recv_message_from_parent
[Feature] Receive character string from parent process.
[Function definition]
void bp_send_message_to_parent(
char *message) /* Received message (output)
subroutine bp_recv_message_from_parent(
character(*) message)
[Return value] none
[Details] For receiving character string length, at least 4 bytes of character length is required.


3-4. bp_put_data
[Feature] output double precision numeric data.
[Function definition]
void bp_put_data(
double *data /* send data (input)
integer *count /* send data count(input)
char *unit /* unit system of data (input)
char *kind /* data kind(input)
char *file) /* file name (input)
subroutine bp_put_data(
real*8 data(*)
integer count
character(*) unit
character(*) kind
character(*) file)
[Return value] none
[Details] Specify unit for data with "au", "kcal".
Data kinds are 4 kinds below.
"char" : charge
"cord" : coordinate
"ener" : energy
"forc" : force


3-5. bp_get_data
[Feature] Input double precision numeric data.
[Function definition]
void bp_get_data(
double *data /* send data (output)
integer *count /* send data count(I/O)
char *unit /* unit system of data (input)
char *kind /* data kind (input)
char *file) /* file name (input)
subroutine bp_get_data(
real*8 data(*)
integer count
character(*) unit
character(*) kind
character(*) file)
[Return value] none
[Details] Unit conversion based on specified unit system and data kind.
Specify unit for data with "au", "kcal".
Data kinds are 4 kinds below.
"char" : charge
"cord" : coordinate
"ener" : energy
"forc" : force


4. Error message
In bp_wrapper, if error is detected at the time of execution, execution will be stopped.
ERR01: Length of character string of parts specified in set_mode is not 1~31
ERR02: Length of character string of mode specified in set_mode is not 4
ERR03: The character string of mode specified in set_mode is neither "mpi" nor "uds".
ERR04: message length in send_message* is not 4.
ERR05: message content in send_message* is not correct.
ERR06: message length in recv_message* is not 4.
ERR07: length of unit in *_data* is not 4.
ERR08: length of kind in *_data* is not 4.
ERR09: length of file in put_data* is not 1～32.
ERR010: data exchange method is not specified in put_data
ERR011: length of file in get_data* is not 1～1024
ERR012: received data count in get_data is more than count
ERR013: data exchange method is not specified in get_data
ERR014: inputted data and requested data is different in kind


5. UDSXML format
In case of udsxml mode, file for the data exchange will be generated in the following format.
This data format is saved in the BASE64 form.
<?xml version="1.0" encoding="UTF-8"?>
<uds_data size="8" count="data number" unit="unit system" form="b64">
<uds_content>data classification</uds_content>
<uds_comment>BioPhuga data</uds_comment>
<uds_array_count>"uds_array"number</uds_array_count>
<uds_array seq="1" element="character" length="64">BASE64 form actual count data </uds _array>
..
/uds_data>


Copyright (C) 2003 Hitachi, Ltd. All rights reserved.
Author : Shirun Ho (Hitachi, Ltd.)
Takashi Kurosawa (Hitachi East Japan Solutions, Ltd.)
Disclaimer : Hitachi Ltd. makes no warranties, express or implied, as to the suitability of this software for any purpose whatsoever. This software can be downloaded and used at user responsibility. Hitachi Ltd. assumes no responsibility for those unusual occurrences where the software has adverse effects on user computers.