MMDB-API  (draft document February 7 1996)

Molecular Modeling Database Application Programming Interface.
Author C. Hogue 
Contributors:  S. Bryant, H. Ohkawa, J. Kans, A. Smirnov, J. Ostell


Contents:
    INTRODUCTION
    MMDB-API DESIGN CONSIDERATIONS
    MMDB-API DATA ABSTRACTION
    MODELSTRUC DATA NODES
    MMDB-API EXAMPLE
    MMDB-API Routines 
      MMDB-API Interface Routines
      ASN.1 MODEL INDEX <> NODE POINTER CONVERSION:
      MODEL TRAVERSERS
      OUTPUT
      COMPUTATIONAL GOODIES
      MACROS
 



http://www.ncbi.nlm.nih.gov/Structure for the latest updates to MMDB-API.
____________________________________________________________________
INTRODUCTION:



MMDB (Molecular Modelling DataBase) is NCBI's 3-dimensional structure service.
The major source of MMDB data is from experimental X-ray crystallographic or 
NMR data from the Brookhaven Protein Database (PDB).  

NCBI's has a complete ASN.1 specification for storage and interchange of
biochemical structure data. The development of the Molecular Modelling DataBase
(MMDB) and the rationale for the use of ASN.1 are discussed at length 
elsewhere.   The ASN.1 data specification is not a prerequisite for using
MMDB-API, as it is parsed into complete and comprehensive memory data 
structures by MMDB-API.  

An ASN.1 Biostruc can represent a  3D structure consisting of several types of 
experimental and derived data.  The Biostruc data consists of (a) bibligraphical
and historical data; (b) a single, unambiguous chemical-graph (i.e. the 
molecule's skeletal path of atoms and bonds); (c) one or more sets of 3D model 
data consiting of locations in space ( X, Y, Z coordinates); and (d) features 
associated with (b) and/or (c).  

MMDB-API is written under the NCBI Software Development Toolkit (SDK), 
required for implementing MMDB-API.  An Applications Programming Interface 
(API) is a set of computer algorithms and programs that allow convenient 
access to data.  

The purpose of MMDB-API is to provide a programmer with the means 
for accessing and computing on the structural data that is transmitted
in the ASN.1 format.  MMDB-API's principal task is to restructure the 
in-memory image of the ASN.1 data to make it computable.  The internal 
representation of the ASN.1 Biostruc is, under MMDB-API converted into a
hierarchical C data structure known as a "Modelstruc".

MMDB-API provides all the C routines in a library in order to 
service the I/O between these three layers,

ASN.1                   C Object         MMDB-API
Specification           Loaders          C Data Structures

file                    Memory           Memory
Biostruc (ASN.1)  <=>   Biostruc   <=>   Modelstruc

Thus you can start computing at the highest-layer, MMDB-API
immediately, without becoming an expert in parsing, file or network I/O,
or the ASN.1 Biostruc file specification.

MMDB-API has been created with some very complex data structures.
You may not need to compute within these.  MMDB-API has some powerful methods 
of obtaining sub-sets of structure data using routines called "traversers".  
These can be applied to cast the data you require into more simple 
data structures thay you design and operate on.  By writing, modified 
data back into the MMDB-API data structures, one can save the results
in the correct ASN.1 data specification automatically.

MMDB-API should not be discounted on the basis of its data structure complexity,
because it is probably the most robust and reproduceable means for obtaining
structure data from a file format and getting it into memory in the first 
place.  

MMDB-API has provided for an astonishingly efficient amount of code-re-use.  
Consider only that the PDB converter is less than
1300 lines of code, and the Kinemage renderer makes 4 different kinds of
renderings, add textual annotation, and is less than 1600 lines of code.   



____________________________________________________________________
MMDB-API DESIGN CONSIDERATIONS

A program called asncode, (NCBI Toolkit) provides a means for taking
an ASN.1 data specification, and generating C data structures, and 
functions that provide memory management and I/O.  This is called the
"object loader layer".  The data structures paralell the ASN.1 data
specification.  A Biostruc can be loaded into memory and manipulated 
in memory directly without any alteration to these ASN.1-derived C data 
structures.   

Unfortunately, the Biostruc C in-memory image, derived from the ASN.1 
specification is ill-suited for computation.   MMDB-API adds an 
additional layer, the Modelstruc, to optimize the in-memory data structure 
for computational purposes. 

Why is the ASN.1-derived C data structure not suited for computation?
Three types of changes are neccesary, data type conversion, 
data instantiation and the addition of explicit "backwards" pointers.  
None of these affect or add to the content of the data, merely they
are data reorganizations.

The internal represenation of coordinate floating point data in the
ASN.1 Biostruc is as an integer value and integer scale factor.  
These must be converted to floating point for computation, hence 
data type conversion must be performed.

Chemical graphs are really saved as indices into residue dictionaries,
both standard and non-standard (local dictionaries). Therefore, to reconstruct 
the graph, each residue (bonds and atoms) must be copied or instantiated 
from the dictionary.

There are no pointer references from the  "chemical graph" to the "location" 
data (i.e. the X, Y, Z coordinates). Rather there are only references from the 
location back into the chemical graph.  These must be interpreted at load-time 
and resolved, hence the addition of explicit backwards pointers.

For computational purposes, one must have a way of finding the chemical graph 
from the location, and the location from the chemical graph.  
In addition, given the location of an atom, one needs a
way of determining its bonded-neighbors, through-space non-bonded neighbors,
its parent molecule and structure.  There is a need to have some of these 
linkages availiable in a pre-computed and computed on-the-fly basis, and the
emphasis in the data structure design has been to use pointers and data
structures in order to reduce the coding and logic required to traverse
the data.  

The Modelstruc is a hybrid data stucture, containing significant portions
of the original ASN.1 derived C structures.  
The portions that remain unchanged after the object-loader phase are, in
general, the descriptive parts. These include bibliographic
and identifier information.  These parts of the data structures are
preserved because there is a large set of NCBI programming that
can use the ASN.1 derived C types as-is.  

Given that some compuations on the Modelstruc cannot be forseen in the
making of the API, the Modelstruc may be manipulated directly.  
Data hiding has not been strongly enforced by MMDB-API and virtually
all the library routines are public at the current time.

Special attention has been paid to the free-ing of memory in MMDB-API, as 
a Structure is freed with a "hierarchical collapse".  This means if you
free something you aren't supposed to (like a string) and don't null out
all the pointers in the structure that point to it (its parents, its children),
MMDB-API free-ing will fail.  More safe free-ing routines will be added as
MMDB-API develops.  



Variable Names and Hungarian Notation:

Code for the MMDB-API attempts to employ Hungarian Notation, whereas the bulk
of the NCBI toolkit has no structured way of defining variables with the
exception of Vibrant objects.  You will either love or hate my notation,
but the reason it was implemented was to reduce bugs, which it does!  

Data structures such as doubly-linked lists and singly-linked-lists are 
maintained by NCBI toolkit core routines.  A pointer to a singly-linked-list
node which contains a pointer to a MAD node, is a PVNMA a "Pointer to ValNode
to ModelAtom"  and a pointer to a doubly-linked list node which contains a 
pointer to a MMD is a PDNMM, a "Pointer to DValNode to ModelMolecule".

Using Hungarian notation, a data type prefix is prepended to a variable name,

a CharPtr is a "pc" meaning pointer to char.
The "p" is put first so that equivalencies of data types is spotted easier:
e.g.

pcFetch = &mystring;
the "p" on the left indicates that the address on the right is an appropriate
cast, whereas
Fetch = &mystring;
tells nothing about whether the address of mystring is appropriate as
a value to insert into Fetch,
without examining the *.h file or wherever Fetch was declared.

In MMDB-API, the abbreviations MS, MA, MM, etc form specific parts of the
Hungarian Notation prefixes:
e.g. the variable pdnmsList is a "P"ointer to "D"Val"N"ode to "M"odel"S"truc 
and the variable name is List.  A declaration of this variable would be:
PDNMS pdnmsList;


_____________________________________________________________________________
MMDB-API DATA ABSTRACTION:


In the conversion of the ASN.1 Biostruc to the C Modelstruc, the 
fundamental changes in the data are that: 

A) Everything is instantiated. 
e.g: In a given Biostruc, there may be many references to the dictionary
graph for "Phe", but there is only one copy of the "Phe" chemical graph
(i.e. the dictionary one).  In the Modelstruc, the "Phe" chemical graph
is instantiated for each "Phe" in a protein.  Likewise there is a list of 
each and every bond in the complete chemical graph.  

(B) All "indicies" and "id's" become C pointers to "nodes" containing the data.
e.g: An "atom" node contains information about the chemical graph part of the 
atom (bonds, name, etc).  It also contains a list of "locations" 
(X,Y,Z coordinates) that come from each structural model present in the ASN.1.  
An atom can have an unlimited number of "locations".  Likewise
an atom contains a complete list of bonds.   The number of bonds an atom
can have is not chemically constrained, rather it is unlimited (and can
include virtual bonds).  The bond list is a list of pointers to "bond"
nodes which link atoms (NOT LOCATIONS) together and indicate what type
the bond is (i.e. single, double, etc).  


There are 4 C functions one gets from each ASN.1 type "Xx" after making
"object loaders" with asncode:
(1) A memory-free-er XxFree().
(2) A memory-allocater XxNew(). 
(3) A read function XxAsnRead(). 
(4) A write funciton XxAsnWrite().  

In addition, one can refer to structure Xx in memory with a pointer of type
XxPtr. 

Similarly, the Modelstruc can be referred to by a
single pointer, and can be freed with a single function.  However, the act
of making a new unpopulated Modelstruc is complicated, and there will
be a provision for special routines to make de-novo structures.
The Modelstruc is currently instantiated by first reading in a
valid Biostruc with BiostrucAsnRead(), then it is converted into a Modelstruc
using MMDB-API routines.  MMDB-API if fully capable of handling a virtually 
unlimited number of structures in memory, providing there is room for them.

Modelstruc Limits:
Atoms - only by memory 
Molecules - only by memory
Residues - only by memory
Structures - only by memory
Models - only by memory 
Features - only by memory


In addition to the "Modelstruc",  a further conversion of the data to and from a 
variety of data arrays and matricies can be easily performed.  This can be used
to allow the application of array- and vector-based algorithms (e.g. Fortran) 
without extensive reprogramming of the internal logic of these programs.  
This paradigm can be convenience to an established body of programmers and 
programs which work in this fashion.


The output or "writing" of a Modelstruc  involves a conversion back to a valid 
in-memory C Biostruct, at the "object loader" layer then the writing 
out of the ASN.1 Biostruc using BiostrucAsnWrite.  In the future we hope one
will be able to instantiate the chemical-graph portion of a Modelstruc
from an ASN.1 sequence or from other data types.



___________________________________________________________________________
MODELSTRUC DATA NODES

There are 9 Main types of data nodes in a Modelstruc.
  
NAMING CONVENTIONS:
MS "ModelStruc"  
MSD is "ModelStrucData"
PMSD is "Pointer to MSD"

likewise for:
MM "ModelMolec",    MMD "ModelMolecData",    PMMD "Pointer to MMD"
MG "ModelGraph",    MGD "ModelGraphData",    PMGD "Pointer to MGD"
MA "ModelAtom",     MAD "ModelAtomData",     PMAD "Pointer to MAD"
MB "ModelBond",     MBD "ModelBondData",     PMBD "Pointer to MBD"
MD "ModelDensity",  MDD "ModelDensityData",  PMDD "Pointer to MDD"
MO "ModelObject",   MOD "ModelObjectData",   PMOD "Pointer to MOD"
AL "AtomLocation",  ALD "AtomLocationData",  PALD "Pointer to ALD"
ML "ModelLocation", MLD "ModelLocationData", PMLD "Pointer to MLD"

A Modelstruc is loosely defined as:
A doubly-linked list containing MSD, containing:
  A doubly-linked list containing MMD, containing:
    A doubly-linked list containing MGD, containing:
       MAD, MBD (interconnected by pointers):
         MAD contains:
	   a linked-list of of locations - ALD's...
	   a linked-list of its own bonds - PMBD's
         MBD contains:
	   bond type information
	   2 pointers - PMAD - to the atom endpoints
    various lists of MAD, MBD (like disulfide bonds)
  various lists of MAD, MBD (like alpha carbons)
  various lists of MOD (objects - bricks, spheres, surfaces, etc)
  various lists of MDD (grid density data)

The root node MSD also contains
  a pointer to the ASN.1 Biostruc which can be 
   the entire Biostruc OR the non-redundant portion.
  pointers to the Models MLD...
  pointers to information & bibliographic data.
  pointers to local & global chemical graph dictionaries.
  pointers to Biostruc-features.
  global rotation/translation matricies to be applied to all locations.
  bounding box.
  rendering information.



The Linked-lists and doubly-linked list nodes contain
the above named data nodes.  Pointers to nodes have
naming prefixes:
PDN  "P"ointer to "D"val"N"ode.  A Doubly-linked list.
PVN  "P"ointer to "V"al"N"ode.   A Singly-linked list.
  
PDNMS "ModelStruc",   Contains a PMSD "Pointer to MSD"
PDNMM "ModelMolec",   Contains a PMMD "Pointer to MMD"
PDNMG "ModelGraph",   Contains a PMGD "Pointer to MGD"
PVNMA "ModelAtom",    Contains a PMAD "Pointer to MAD"
PVNMB "ModelBond",    Contains a PMBD "Pointer to MBD"
PVNMD "ModelDensity", Contains a PMDD "Pointer to MDD"
PVNMO "ModelObject",  Contains a PMOD "Pointer to MOD"
PVNAL "AtomLocation", Contains a PALD "Pointer to ALD"
PDNML "ModelLocation",Contains a PMLD "Pointer to MLD"


 

OBJECT-ORIENTED NODE STRUCTURE:

Each node, MSD, MMD, MGD, MAD, MBD, ALD (except MLD) can be referenced by the 
sub-type FB (FlagBlock) with  a PFB (pointer to FlagBlock). 
This allows one to abstract each data node for common routines,
e.g. a routine that returns a three-dimensional bounding box could use
whole structures (MSD), whole molecules (MMD) residues (MGD) or atoms (MAD)
as input data.  With a PFB pointer, all these data types can be referenced 
from a single routine.  While not quite OOP, it does reduce the code involved.
Other tricks are availiable, i.e. given a PFB pointer to some "Model Object"
one can determine its type (MSD,MMD, etc), its indicies and its parent objects,
(e.g. an atom's parent molecule).   This also makes all objects "clickable"
in a 3D graphics viewer.  If the viewer returns one pointer, one can traverse
the pointer links back to find out what it is (bond or atom) and find out
who its parents are (residue, molecule, structure).  

The internal C definition of components in each node are found in mmdbapi1.h


____________________________________________________________________________
MMDB-API EXAMPLE:


With the MMDB-API, the programmer does not need to parse the data file.  
The task are, Open MMDB-API,  Load an ASN.1 Biostruc,  Register it with
MakeAModelstruc and you obtain a pointer of type PDNMS to the structure,
which is the most commonly used argument in MMDBAPI functions.

You can register as many structures as you wish, they
form a list in memory that is free-ed when CloseMMDBAPI is called.


Here's some sample code that uses MMDB-API prints all the atomic XYZ coordinates
for a given ASN.1 MMDB file (testapi.c).

_______________________________________
#include <ncbi.h>  /* the NCBI SDK header */
#include <asn.h>   /* the ASN.1 header */
#include <mmdbapi.h>   /* the MMDB-API header */

/********************************************************* 
 *The NCBI argument routines are described in            *
 *   the NCBI Software Development Toolkit               *
 *********************************************************/

#define NUMARGS 2

Args myargs[NUMARGS] = {
        {"Input String",NULL,NULL,NULL,FALSE,'s',ARG_FILE_IN,0.0,0,NULL},
	{"Model Level \n0 = Atoms; 1=BB; 2=all PDB; 3=VECT; ","0","0","3",TRUE,'m',ARG_INT,0.0,0,NULL}
      };



/********************************************************* 
 *The CALLBACK routine.                                  *
 * Executed as the traverser visits each node.           *
 *  If the node is an atom, it prints the atom's name,   *
 *   and the first model's                               *
 *   X, Y, and Z values for the atom                     *
 *********************************************************/

static void DoXYZ(PFB pfbThis, Int4 iModel, Int4 iIndex, Pointer ptr)
{
  PMAD pmadAtom;
  PALD paldLoc;

    /* pfbThis points to a generic data node */
    /* we want only ModelAtomData or MAD nodes */
    if (IsAtomNode(pfbThis))
      {
          /* cast to the correct PMAD pointer type */
	  pmadAtom = (PMAD) pfbThis;
	  
	  /* get the locations (XYZ coords node) for this atom, and model */
	  paldLoc = GetAtomLocs(pmadAtom, iModel);
	  
	  /* go through each location for this particular atom and model */ 
	  while (paldLoc) 
	    {
             /* print the Atom name and location data */
	     printf("Atom, %s, X=%f, Y=%f,  Z=%f \n", 
                AtomPDBName(pmadAtom), 
	        AtomLocX(paldLoc),  
                AtomLocY(paldLoc),  
                AtomLocZ(paldLoc));
	     paldLoc = paldLoc->next; /* get next location */
	    }
      }
}



/********************************************************* 
 *The Main() function,  built according to the NCBI      *
 *   Software Development Toolkit specifications, lends  *
 *   portability between GUI and non-GUI platforms       *
 *********************************************************/

Nlm_Int2 Main ()
{
  Int2 iTest;
  PDNMS pdnmsModelstruc;
  BiostrucPtr pbsBiostruc;
  

        
   	if (! GetArgs("MMDB-API Example",NUMARGS,myargs))
		return 1;
	 
	/* Initialize MMDB-API  */ 

 	if (! OpenMMDBAPI(0, NULL, (Int2) myargs[1].intvalue)) 
	  {
	        printf("Have not opened mmdbapi");
	        return 2;	
	  }
	/* load an ASN.1 Biostruc */
	pbsBiostruc = FetchBiostrucPDB(myargs[0].strvalue, myargs[1].intvalue, 100);
        if (pbsBiostruc == NULL)
	  {
	        printf("Have not fetched Biostruc");
		return 3;
	  }

	/* convert it into a Modelstruc pointed to by pdnmsMain */
	pdnmsModelstruc= MakeAModelstruc(pbsBiostruc);		
	if ( pdnmsModelstruc == NULL )
	  {
	        printf("Have not not Converted Biostruc");
	        return 4;
	  }
		
	/* Traverse all the ATOM nodes in each pdnmsMain, */
	/* doing the function DoXYZ at each node for each model */  

 	iTest = TraverseModels(	pdnmsModelstruc,
				TRAVERSE_ATOM, 
				0,NULL,
				(pNodeFunc)(DoXYZ));
	  

	/* Free the Modelstruc (and its enclosed Biostruc) */	  
 	/* FreeAModelstruc(PDNMS pdnmsThis); not necessary */
	/* This can be done individually - but all Modelstrucs */
        /* remaining are freed in CloseMMDB-API() */

	/* Shut Down MMDB-API */	

	CloseMMDBAPI();	

 	return TRUE;
}




__________________________________________________________________________
 ___________________________________________________________________________
MMDBAPI Interface routines:

Main routines:

Int2  OpenMMDBAPI(Byte bExtent, CharPtr pcDictName);
Boolean IsMMDBAPIOpen(void);
BiostrucPtr FetchBiostrucPDB(CharPtr pcAcession, Int4 iModelLevel, Int4 iMaxModels);
PDNMS MakeAModelstruc(BiostrucPtr pbsThis);

Safe Free-ers (so far):

Boolean FreeSingleModel(PDNMS pdnmsThis, Int2 iModel);
void  ClearStructures(void);
void FreeAModelstruc(PDNMS pdnmsThis);
void CloseMMDBAPI(void);  /* frees leftovers Modelstruc's */


Settings:

PDNMS  GetPDNMSMain(void);  
PRGD   GetPRGDDictionary(void);
Byte  GetMMDBAPIbExtent(void);
void  ChangeMMDBAPIbExtent(Byte bExtent);

Structure Access:

void SetMasterModelstruc(PDNMS pdnmsThis);
PDNMS GetMasterModelstruc(void);
void SetSelectedModelstruc(PDNMS pdnmsThis);
PDNMS GetSelectedModelstruc(void);
void SetHolderModelstruc(PDNMS pdnmsThis);
PDNMS SwapModelstruc(void);

Access from list of structures:

PDNMS GetFirstModelstruc(void);
PDNMS GetNextModelstruc(void);
PDNMS GetPreviousModelstruc(void);


Keeping lists of selected nodes:

ValNodePtr AddPFBSelect(PFB pfbThis);
void ClearPFBSelectList(void);
void UndoPFBSelectList(void);

Miscellaneous:

CharPtr GetStrucStrings(PDNMS pdnmsThis, Int4 iPickType);
Int4 MakeHashChange(PDNMS pdnmsThis);
Int4   CountModelstrucs(void);
_pmmdbAPI NewMMDBAPI(void);


___________________________________________________________________
ASN.1 MODEL INDEX <> NODE POINTER CONVERSION:

 
The ASN.1 definition of the Biostruc refers to the chemical graph by 
MoleculeID, ResidueID (same as Graph here), and AtomID.
These routines find the appropriate node in the Modelstruc, given the
ID's.

PMAD 	AtomFromMMDBIndex(PDNMS pdnmsList, Int2 iStru, Int2 iMol, Int2 iGraph, Int2 iAtom);
PMGD 	GraphFromMMDBIndex(PDNMS pdnmsList, Int2 iStru, Int2 iMol, Int2 iGraph);
PMMD 	MolFromMMDBIndex(PDNMS pdnmsList, Int2 iStru, Int2 iMol);


PALD	GetLocation(PALD paldList,  Int2 iCoord,  Char cAlt);
PALD	GetAtomLocs(PMAD pmadThis,  Int2 iModel);
PMGD	GetParentGraph(PFB pfbThis);
PMMD	GetParentMol(PFB pfbThis);  
PMSD	ToMSDParent(PFB pfbThis);  


Generic conversions:
PFB	PFBFromVN(ValNodePtr pvnModel);
PFB	PFBFromDN(DValNodePtr pdnModel);
DValNodePtr DNFromPFB(PFB pfbThis);
Int2	IndexFromNode(PFB pfbNode);  


Lookup routines:
NOTE: You are not given your own copy of a string, you always get a
pointer to a string in memory.  Do not free CharPtrs returned 
by these functions!

Int2	ParentMolNum(PFB pfbThis);
CharPtr	ParentMolName(PFB pfbThis);
CharPtr	ParentGraphPDBNo(PFB pfbThis);
CharPtr	ParentGraphPDBName(PFB pfbThis);
CharPtr	ParentGraphIUPAC1(PFB pfbThis);
Int2	ParentGraphNum(PFB pfbThis);
CharPtr LIBCALL ElementName(Int1 iAtomicNo);
CharPtr LIBCALL AminoAcidName(Char cThis, Int2 iRetCode);

 


_______________________________________________________________
MODEL TRAVERSERS:

The following routines use pointers to functions which allow the programmer
to attach a "computation" to a routine that "walks" the Modelstruc. 


Int2 TraverseAll( DValNodePtr pdnModel, Int4 iModel, Int4 iIndex, 
			  Pointer ptr, pNodeFunc pfnCallMe);

	 Walks the structure children from the current pointer.  Performs
	 (*pfnCallMe)(pfbThis, iModel, iIndex, ptr) at each data node (as Flags Block).

	The argument pdnModel can be either a PDNMS, PDNMM, or PDNMG.
	Note that PDNMS to traverse a single structure, but 
	PDNMM and PDNMG continue traversing from the point where called
	down the linked list.  Therefore if you want to traverse only
        one molecule, say pmmdThis, use the pmmdThis->pdnmgHead pointer 
	that hangs off the molecule as the argument for the traverser.


MODEL-SPECIFIC TRAVERSERS:
These routines allow you to traverse one specific model
        or all the models.

Int2 TraverseOneModel(DValNodePtr pdnModel, Int2 iTraverse, Int2 iModel, 
			Int4 iIndex, Pointer ptr, pNodeFunc pfnCallMe);

Int2 TraverseModels(DValNodePtr pdnModel, Int2 iTraverse, 
     Int4 iIndex, Pointer ptr,  pNodeFunc pfnCallMe);

	use the iTraverse flag as:
#define TRAVERSE_ALL 0
#define TRAVERSE_MOLECULE 1
#define TRAVERSE_GRAPH 2
#define TRAVERSE_ATOM 3
#define TRAVERSE_BOND 4
#define TRAVERSE_SOLID  5
#define TRAVERSE_IBOND 6


NODE-SPECIFIC TRAVERSERS:
These only visit the PFB nodes stated in their names, and ignore the others.
They are usually called by TraverseOneModel and TraverseModels. 
They are much faster than TraverseAll because they only call the function at 
the specified node type.


Int2 TraverseIBonds( DValNodePtr pdnModel, Int4 iModel, Int4 iIndex, 
			  Pointer ptr, pNodeFunc pfnCallMe);

 	 Walks all the inter-res or inter-mole bond children from 
	 the current pointer.
	 Can start from MSD, MMD, MGD, MBD (self) 
	 Performs(*pfnCallMe)(pfbThis, iModel, iIndex, ptr) at each bond node.


Int2 TraverseBonds( DValNodePtr pdnModel, Int4 iModel, Int4 iIndex, 
			  Pointer ptr, pNodeFunc pfnCallMe);

 	 Walks all the bond children from the current pointer.
	 Can start from MSD, MMD, MGD, MBD (self) 
	 Performs(*pfnCallMe)(pfbThis, iModel, iIndex, ptr) at each bond node.



Int2 TraverseAtoms( DValNodePtr pdnModel, Int4 iModel, Int4 iIndex, 
			  Pointer ptr, pNodeFunc pfnCallMe);
 	Walks all the atom children from the current pointer.
	 Can start from MSD, MMD, MGD, MAD (self).
	 Performs (*pfnCallMe)(pfbThis, iModel, iIndex, ptr) at each atom node.
	



Int2 TraverseGraphs( DValNodePtr pdnModel, Int4 iModel, Int4 iIndex, 
			  Pointer ptr, pNodeFunc pfnCallMe);
	 Walks all the model children from MSD, MMD
	 Performs (*pfnCallMe)(pfbThis, iModel, iIndex, ptr) at each graph node.




Int2 TraverseMolecules( DValNodePtr pdnModel, Int4 iModel, Int4 iIndex, 
			  Pointer ptr, pNodeFunc pfnCallMe);
 	 Walks all the model children from MSD
	 Performs (*pfnCallMe)(pfbThis, iModel, iIndex, ptr) at each molecule node. 



Int2 TraverseSolids( DValNodePtr pdnModel, Int4 iModel, Int4 iIndex, 
			  Pointer ptr, pNodeFunc pfnCallMe);


	
 		

 
 

__________________________________________________________________________
OUTPUT:
 
ASN.1 file generators
Boolean WriteAsnModelList(PDNMS pdnmsThis,   Int2 iNumModels,  Int2Ptr i2Vec,  
				    CharPtr pcSave,  Byte bSave );
Boolean WriteAsnOneModel(PDNMS pdnmsThis,  Int2 iModel,  CharPtr pcSave,  Byte bSave);
Boolean WriteAsnAllModel(PDNMS pdnmsThis,  CharPtr pcSave,  Byte bSave);
Boolean WriteAsnLocalDict(PDNMS pdnmsThis, CharPtr pcSave,  Byte bSave,  Boolean SaveId);


PDB file generators:
Int2	WritePDBModelList(PDNMS pdnmsThis,  FILE *pFile,  Int2 iNumModels,  Int2Ptr i2Vec );
Int2	WritePDBOneModel(PDNMS pdnmsThis,  FILE *pFile,  Int2 iModel);
Int2	WritePDBAllModel(PDNMS pdnmsThis,  FILE *pFile);


Kinemage file generators:
Int2	WriteKinModelList(PDNMS pdnmsThis,  FILE *pFile,  Int2 iColor, Byte bKinRender,
				 Int2 iNumModels,  Int2Ptr i2Vec );
Int2	WriteKinOneModel(PDNMS pdnmsThis,  FILE *pFile, Int2 iColor, Byte bKinRender, Int2 iModel);
Int2	WriteKinAllModel(PDNMS pdnmsThis, FILE *pFile, Int2 iColor, Byte bKinRender);

iColor types:

bKinRender types:
#define KIN_MULTANIM    0x20  /* forces KIN_COLOR_NUMBER */
#define KIN_ALTCONF     0x10  
#define KIN_HET         0x08   /* default */
#define KIN_RESIDUE     0x04 
#define KIN_BACKBONE    0x02   
#define KIN_VIRTUAL     0x01   /* default */
#define KIN_DEFAULT     0x00  /* forces KIN_VIRTUAL */

#define KIN_COLOR_DEFAULT 0  /* forces KIN_COLOR_NUMBER */
#define KIN_COLOR_NUMBER  1  /* default */
#define KIN_COLOR_TYPE    2 
#define KIN_COLOR_TEMP    3  /* forces Temp groups only */ 
#define KIN_COLOR_ATOM    4  /* forces Element groups only */






__________________________________________________________________________
COMPUTATIONAL GOODIES:

FloatLo LIBCALL AtomDistanceSq(PMAD pmadFrom, PMAD pmadTo, Int2 iModel, Char cAlt);


 

___________________________________________________________________________
MACROS:

The "Is" macros are used to triage PFB nodes and to query their contents
as booleans.  You must cast to a PFB if you use these macros with
known type data, e.g:

if (IsNA((PFB)pmsdThis))
  {
    /* this structure contains a Nucleic Acid molecule */
    /* it may contain other things... */
  }

if (IsNA((PFB)pmmdThis))
  {
    /* this molecule is a Nucleic Acid */
  }

Note that macros aren't used in mmdabpi[1-3].c code.  
That's because they weren't defined until after that code was written.
These are defined in mmdbapi.h.



Use these with any PFB node, esp. when doing TraverseAll...
  IsAtomNode(pfb)      ((int) pfb ->bMe == AM_MAD)
  IsBondNode(pfb)      ((int) pfb ->bMe == AM_MBD)
  IsGraphNode(pfb)     ((int) pfb ->bMe == AM_MGD)
  IsMoleculeNode(pfb)  ((int) pfb ->bMe == AM_MMD)
  IsObjectNode(pfb)    ((int) pfb ->bMe == AM_MOD)
  IsDensityNode(pfb)   ((int) pfb ->bMe == AM_MDD)
  IsStructureNode(pfb) ((int) pfb ->bMe == AM_MSD)
  IsAtomLocNode(pfb)   ((int) pfb ->bMe == AM_ALD)

Use these when IsStructureNode(pfb) OR IsMoleculeNode(pfb) == TRUE 
  IsIon(pfb)		(pfb ->bWhat & (Byte) AM_ION)
  IsRNA(pfb)		(pfb ->bWhat & (Byte) AM_RNA)
  IsDNA(pfb)		(pfb ->bWhat & (Byte) AM_DNA)
  IsNA(pfb)		((pfb ->bWhat & (Byte) AM_RNA) || (pfb ->bWhat & (Byte) AM_DNA))
  IsProtein(pfb)		(pfb ->bWhat & (Byte) AM_PROT)
  IsNAorProtein(pfb)     ((pfb ->bWhat & (Byte) AM_RNA) || (pfb ->bWhat & (Byte) AM_DNA)\
 || (pfb ->bWhat & (Byte) AM_PROT))
  IsWater(pfb)		(pfb ->bWhat & (Byte) AM_WAT)  
  IsSolvent(pfb)		((pfb ->bWhat & (Byte) AM_SOL) || (pfb ->bWhat & (Byte) AM_WAT))
  IsHeterogen(pfb)	(pfb ->bWhat & (Byte) AM_HET)
  IsOtherPolymer(pfb)	(pfb ->bWhat & (Byte) AM_POLY)

Use these when IsGraphNode(pfb) == TRUE 
  IsGraphRNABase(pfb)	(pfb ->bWhat & (Byte) RES_RNA)
  IsGraphDNABase(pfb)	(pfb ->bWhat & (Byte) RES_DNA)
  IsGraphNABase(pfb)	((pfb ->bWhat & (Byte) RES_RNA) || (pfb ->bWhat & (Byte) RES_DNA))
  IsGraphAminoAcid(pfb)	(pfb ->bWhat & (Byte) RES_AA)
  IsGraphNAorAA(pfb)     ((pfb ->bWhat & (Byte) RES_RNA) || (pfb ->bWhat & (Byte) RES_DNA)\
 || (pfb ->bWhat & (Byte) RES_AA))
 
Use these when IsGraphNode(pfb) AND IsGraphAminoAcid(pfb) == TRUE 
  IsAAInPDBSS(pfb)	(pfb ->bPDBSecStru)
  IsAAInPDBHelix(pfb)   (pfb ->bPDBSecStru & (Byte) SS_HELIX)
  IsAAInPDBSheet(pfb)   (pfb ->bPDBSecStru & (Byte) SS_SHEET)
  IsAAInPDBStrand(pfb)  (pfb ->bPDBSecStru & (Byte) SS_STRAND)
  IsAAInPDBTurn(pfb)    (pfb ->bPDBSecStru & (Byte) SS_TURN)
  IsAAInNCBISS(pfb)   (pfb ->bNCBISecStru)
  IsAAInNCBIHelix(pfb)  (pfb ->bNCBISecStru & (Byte) SS_HELIX)
  IsAAInNCBISheet(pfb)  (pfb ->bNCBISecStru & (Byte) SS_SHEET)
  IsAAInNCBIStrand(pfb) (pfb ->bNCBISecStru & (Byte) SS_STRAND)
  IsAAInNCBITurn(pfb)   (pfb ->bNCBISecStru & (Byte) SS_TURN)


Use these when IsAtomNode(pfb) == TRUE 
  IsAtomBackBone(pfb)     (pfb ->bWhat & (Byte) AM_BACKBONE)
  IsAtomCAlpha(pfb)       (pfb ->bWhat & (Byte) AM_CALPHA)
  IsAtomPAlpha(pfb)       (pfb ->bWhat & (Byte) AM_PALPHA)
  IsAtomAlpha(pfb)        ((pfb ->bWhat & (Byte) AM_CALPHA)  ||  (pfb ->bWhat & (Byte) AM_PALPHA))
  IsAtomOCarbonyl(pfb)    (pfb ->bWhat & (Byte) AM_OCARBNYL)
  IsAtomCBeta(pfb)        (pfb ->bWhat & (Byte) AM_CBETA)
  IsAtomNBeta(pfb)        (pfb ->bWhat & (Byte) AM_NBETA)
  IsAtomBeta(pfb)	 ((pfb ->bWhat & (Byte) AM_CBETA) || (pfb ->bWhat & (Byte) AM_NBETA))
  IsAtomC1Ribose(pfb)     (pfb ->bWhat & (Byte) AM_C1RIBOSE)
  IsAtomC4Ribose(pfb)     (pfb ->bWhat & (Byte) AM_C4RIBOSE)

returns a CharPtr:
  AtomPDBName(pfb)         pfb ->pcAName
returns an Int1
  AtomicNumber(pfb)        pfb ->pvnmaLink->choice 


Use these when IsBondNode(pfb) == TRUE 
  IsBondVirtual(pfb)      (pfb ->bWhat & (Byte) BOND_VIRTUAL)
  IsBondPDouble(pfb)      (pfb ->bWhat & (Byte) BOND_PDOUBLE)
  IsBondVanderWaal(pfb)   (pfb ->bWhat & (Byte) BOND_VDW)
  IsBondIonic(pfb)        (pfb ->bWhat & (Byte) BOND_IONIC)
  IsBondHydrogen(pfb)     (pfb ->bWhat & (Byte) BOND_H)
  IsBondTriple(pfb)       (pfb ->bWhat & (Byte) BOND_TRIPLE)
  IsBondDouble(pfb)       (pfb ->bWhat & (Byte) BOND_DOUBLE)
  IsBondSingle(pfb)       (pfb ->bWhat & (Byte) BOND_SINGLE)
  IsBondAromatic(pfb)     ((pfb ->bWhat & (Byte) BOND_PDOUBLE) && (pfb ->bWhat & (Byte) BOND_DOUBLE))

Use these when IsObjectNode(pfb) == TRUE 
  IsObjectSphere(pfb)     (pfb ->bWhat & (Byte) OBJ_SPHERE)
  IsObjectCylinder(pfb)   (pfb ->bWhat & (Byte) OBJ_CYLINDER)
  IsObjectBrick(pfb)      (pfb ->bWhat & (Byte) OBJ_BRICK)
  IsObjectTMesh(pfb)      (pfb ->bWhat & (Byte) OBJ_TMESH)
  IsObjectTriangles(pfb)  (pfb ->bWhat & (Byte) OBJ_TRIANGLES)
  IsObjectCone(pfb)       (pfb ->bWhat & (Byte) OBJ_CONE)

Use these when IsAtomLocNode(pfb) == TRUE 
these return FloatLo values
  AtomLocX(pfb)  pfb ->pflvData[0]
  AtomLocY(pfb)  pfb ->pflvData[1]
  AtomLocZ(pfb)  pfb ->pflvData[2]

Use when IsStructureNode(pfb) == TRUE
returns a CharPtr - which you should copy before use
  PDBAccession(pfb)  pfb ->pcPDBName