pfui.txt

一个有用的分子动力学小辅助程序

	FE Urbana 3-oct-1993, 31-oct-1993

	This document describes the new format for potential tables,
	named PFUI (Potential FUnctions Interpolation) to be used by 
	Master and other programs.
	The old format has to be considered discontinued.  All the 
	main potentials currently in use have been converted to the 
	PFUI format.

	----------------------------------------------------------------

	WHY
	===
	The old (1985) format was not adequate to include modern 
	multifunction potential (that is, beyond pair potentials or glue 
	models), and to treat multicomponent systems.  The PFUI table 
	format addresses these issues, and will hopefully provide a 
	structure that will be used for a long time from now on.
	One goal is writing applications supporting different
	potential forms and/or multicomponent systems by simple
	recompilation, or perhaps within the same executable.
	The unformatted version also allows for a compact representation
	and fast loading.

	STRUCTURE OF PFUI FILES
	=======================
	There are two incarnations of PFUI files.  They are completely
	equivalent and they can be converted one into the other in a
	reversible way (no loss of information) on IEEE machines.

	*) ".PFI" files are standard text files, which do not exceed 
	   80 columns for easiness of inspection and transmission by 
	   email. They are opened as FORMATTED in Fortran programs.

	*) ".PUI" files are unformatted files, which can therefore be
	   transported only among machines sharing the same floating
	   point format and Fortran UNFORMATTED file structure.

	Two tools, called pfui and pufi are provided for conversions
	.PFI=>.PUI and .PUI=>.PFI respectively.
	What said below applies to both formats.

	PFUI files will contain one or more "table-units" (TU). The 
	format of each TU is described below.
	Typically, input routines will process an incoming stream of TUs, 
	with no prescribed order.
	After the stream is terminated, a check is made that all the
	required tables have been supplied before starting the
	calculation.

	All the above boils down, in practice, to the following:
	there will be files containing all the TUs required for a
	single element.  For a glue potential, for instance, three
	TUs will probably reside in a single file (containing
	the pair potential, the atomic density and the glue function).
	When a binary alloy potential is developed, the mixed functions
	will put in a third file.  The three files (element A, element B
	and mixed AB interaction) will be concatenated to form the
	input stream of TUs to be supplied for a calculation.
	For a ternary alloy, six files (A,B,C,AB,AC,BC) will be read,
	and so on.

	FORMAT OF A TABLE UNIT
	======================

	NOTE: Tabulations using the "square" of the argument, as in the
	      1985 format for distance-dependent functions, have been
	      eliminated.
	      "Square" tables can still be used in programs, of course,
	      but applications requiring them will have to generate
	      them from the regular tables.   A subroutine is supplied
	      to do this (see below).

	INPUT/OUTPUT ROUTINES
	=====================
	General input and output routines are supplied. These routines
	do not contain any COMMON in order to be shared among various
	programs.  The interface is defined as follows:

	SUBROUTINE PFUIREAD
	-------------------
	This is the general routine to read tables in memory from
	PFUI files.  The users presents a list of desired tables,
	and specifies a PFUI file which is supposed to contain all
	of them.  The routine will go through the file, filling
	all the tables in the user's list as they are encountered.
	A special case is nfun=0, in this case the user just needs
	to know nhamtyp.

	SUBROUTINE PFUIREAD(nunit,pfi,nfun,tutype,ielem,nderiv,ntabdim,
                            nhamtyp,descr,extra,ntab,atumin,atumax,datui,
                            tu,dtu,d2tu,icode)
	
	INPUT:
		nunit:	Fortran unit number for the file.
			-1 is a special code to indicate standard input
			(that is, READ(*,..)) [requires pfi=.true.].
			no open/close actions are done by the routine.
		pfi (logical): if true, a PFI (formatted) file is
			assumed, otherwise a PUI (unformatted).
		nfun:	number of function desired (derivatives should
			not be counted as separate).  nfun can also be
			0: in this case, of all the variables in output
			listed below, only nhamtyp will be returned.
			The routine still consumes the whole file up
			to the end.
		tutype(nfun) (character*2): two-letter code, 
			identifying the functions to be loaded.  
		ielem(3,nfun): atomic number(s) of the element(s)
			for which the function are desired.  Only one
			or two of these numbers are significant (it
			depends on the number of indexes of the
			function).  The routine will read in the
			appropriate position a function found in the
			PFUI file that matches tutype and ielem's.
		nderiv:	maximum derivative needed.  the routine will
			load the function and derivatives up to
			nderiv-th order, if present in the file.
			nderiv can be 0, 1 or 2.
		ntabdim: maximum number of points in a table.  This
			MUST be the first dimension of the tu, dtu
			and d2tu arrays (unless some of them are not
			used because of nderiv).
	
	OUTPUT:
	        nhamtyp: hamiltonian type code, as found in the first
			function stored in the file.
		descr(3,nfun) (character*80): three lines of
			description for each function.
		extra(3,nfun): three extra parameters stored along 
			with the tables. Their definition is left to 
			the user.
		ntab(nfun): number of points in the table
		atumin(nfun): minimum argument for table, corresponds
			to the first point
		atumax(nfun): maximum argument for table, corresponds
			to the last point
		datui(nfun): =(ntab-1)/(atumax-atumin): inverse table
			spacing (required to perform table lookups).
		tu(1..ntab,nfun): function tables.  1..ntab means that
			these are the locations filled, but the first
			dimension of the array must be ntabdim.
		dtu(1..ntab,nfun): first derivative tables;  it can be 
			a dummy placeholder if nderiv=0.
		d2tu(1..ntab,nfun): second derivative tables; it can be 
			a dummy placeholder if nderiv=0 or 1.
		icode:	0: all tables successfully read
			1: error in reading the file
			2: the maximum order of derivative requested is
			   larger than the maximum order stored in the 
			   file, or out of range anyway.
			3: not all of the requested tables could be
			   found in the file (those not found have
			   ntab=0 so the user may look up for them 
			   easily).
			4: a table was found to be too large (ntabdim
			   too small).
			5: the routine's internal buffer is not large 
			   enough for these tables.

	SUBROUTINE PFUIWRIT
	-------------------
	This is the general routine to create a table and write it into
	a PFUI file.  A PFUI file will contain typically the results
	of many calls to PFUIWRIT (for different functions).

	SUBROUTINE PFUIWRIT(nunit,pfi,nhamtyp,descr,tutype,ielem,extra,
                            nderiv,ntab,atumin,atumax,func,icode)
	INPUT:
		nunit:	Fortran unit number for the file.
			-1 is a special code to indicate standard output
			(that is, WRITE(*,..))  [requires pfi=.true.].
			No open/close/rewind actions are done by the 
			routine.
		pfi (logical): if true, a PFI (formatted) file is
			created, otherwise a PUI (unformatted).
		nhamtyp: hamiltonian type code to which this function
			refers. The user is expected to specify the
			same code for different functions located in
			the same PFUI file.
		descr(3) (character*80): three lines of description
		tutype (character*2): two-letters code, identifying
			the table stored
		ielem(3): atomic number(s) of the element(s) to which 
			the function refers.  The second and third 
			atomic number is 0 for functions that depends 
			upon a single element.  The third number is 
			zero for functions that depend only on pairs 
			(and will hopefully always remain zero in 
			practice....).
			In case of symmetrical functions, please put 
			the atomic numbers in ascending order.
		extra(3): placeholder for three extra parameters to be
			stored along with the tables. Their definition 
			is left to the user.  If they are not needed, 
			just define them as 0.d0.
		nderiv:	number of derivatives to be written on tables.
			It can be 0, 1 or 2.   0 means only the function
			and no derivatives, and it's not recommended.
			For MD, 1 is enough.  2 is required to run 
			lattice dynamics programs.
		ntab:	number of points in the table
		atumin: minimum argument for table, corresponds to
			the first point
		atumax: maximum argument for table, corresponds to
			the last point
		func (external): name of subroutine supplying the 
			function values. The subroutine has to be coded 
			as
				SUBROUTINE func(ARG,F,DF,D2F)
			where F, DF, D2F are the function and its first
			two derivatives, evaluated at ARG.
			All arguments must be double precision.
			If second derivatives are not requested, D2F
			can be a dummy placeholder.
	OUTPUT:
		icode:	0: table successfully written
			1: error in writing the file
			2: the maximum order of derivative requested is
			   out of range.
			3: number of points in the table is too small
			   (less than 2)
			4: atumin is not lower than atumax
			5: the routine's internal buffer is not large 
			   enough for these tables.

	OTHER UTILITY ROUTINES
	======================

	SUBROUTINE PFUIINFO
	-------------------
	This is a routine that investigates the contents of a PFUI
	file and reports back some useful information -- but not
	the potential tables.  PFUIREAD must be used to read the
	potential tables.  PFUIINFO followed by PFUIREAD is the
	way to read in a potential about which nothing is known
	in advance.  In particular, nfun, tutype, ielem, nderiv,
	as returned by PFUIINFO can be passed along to PFUIREAD.

	SUBROUTINE PFUIINFO(nunit,pfi,nfunmax,
                            nfun,nhamtyp,descr,tutype,ielem,extra,
	                    nderiv,ntab,atumin,atumax,icode)

	INPUT:
		nunit:	Fortran unit number for the file.
			-1 is a special code to indicate standard input
			(that is, READ(*,..)) [requires pfi=.true.].
			no open/close actions are done by the routine.
		pfi (logical): if true, a PFI (formatted) file is
			assumed, otherwise a PUI (unformatted).
		nfunmax: maximum number of functions allowed.  This
			is usually the dimension of the arrays below,
			as declared by the caller.

	OUTPUT:
		nfun:	number of functions contained in the file 
			(derivatives are not counted as separate).
			If nfun>nfunmax, the arrays below will be only
			partially filled, and icode=3 is returned.
	        nhamtyp: hamiltonian type code, as found in the first
			function stored in the file.
		descr(3,nfun) (character*80): three lines of
			description for each function.
		tutype(nfun) (character*2): two-letter code, 
			identifying each function.
		ielem(3,nfun): atomic number(s) of the element(s)
			for which the function are defined.  Only one
			or two of these numbers are significant (it
			depends on the number of indexes of the
			function).  The non-significant positions
			will be filled with 0's.
		extra(3,nfun): three extra parameters stored along 
			with the tables. Their definition is left to 
			the user.
		nderiv:	minimum derivative order stored in file (that
			is, successful read up to order nderiv is
			guaranteed for any function).  nderiv will be 
			0, 1 or 2.
		ntab(nfun): number of points in each table
		atumin(nfun): minimum argument for table, corresponds
			to the first point
		atumax(nfun): maximum argument for table, corresponds
			to the last point
		icode:	0: everything went as expected and info has
			   been returned
			1: error in reading the file
			2: file appears to be in an illegal format,
			   no function information could be retrieved
			3: the number of functions in the file was
			   larger than nfunmax, so that all the arrays
			   above are filled only partially.
	
	SUBROUTINE PFUIMAP
	------------------
	This routines "remaps" a table into another table, where the
	points are equally spaced in terms of some integer power of the 
	argument.  A typical usage is to construct r**2-spaced tables
	to be used in molecular dynamics programs.
	If several derivatives have to be converted, the routine must 
	be called once for each of them.

	SUBROUTINE PFUIMAP(ntab, atumin, atumax, datui, tu,ipow, oner,
     $                     ntab2,atumin2,atumax2,datui2,tu2,icode)

	INPUT:
		ntab:	number of points in the table
		atumin: minimum argument for table, corresponds to
			the first point
		atumax: maximum argument for table, corresponds to
			the last point
		datui:	inverse table spacing
		tu(ntab): table
		ipow:	power of the argument to which the new table
			will be mapped.  It must be a positive integer.
		oner (logical): if true, the output table will have
			-tu/arg rather than tu.  This is useful to
			make tables of -(1/r)(dV/dr) from a V(r).
		ntab2:	number of points in the output table
	OUTPUT:
		atumin2: minimum argument for table, corresponds to
			the first point
		atumax2: maximum argument for table, corresponds to
			the last point
		datui2:	inverse table spacing
		tu2(ntab2): table
		icode:	0: table mapping successfully done
			1: ipow was 0 or negative
			2: argument scale spans negative numbers,
			   mapping cannot be done.