This documentation is of interest only to the programmer working in the C Language and should really be in the Programming Manual. This a temporary location. The AtomMap module provides 12 functions in its C API. atomnumber Returns the atom (index) number for the given Atom Map object atomproplist Returns a list containing the requested atom properties for all the atoms in the given Atom Map excltypelist Returns a list of atom exclusion type codes for all the atoms in the given Atom Map fpflocation Returns the location of the force parameter directory for the given Atom Map isAtomMap Determines if the given object is an Atom Map mapfromavf Reads the encoded map from an Atom Vector file, creates it and returns the new Atom Map object maps2typecode Returns the hash code of the inclusion atom types of the given two, three or four Atom Map objects readatommap Reads the encoded map in an Atom Vector file and determines if it is for the given object refnumber Returns the reference number for the given Atom Map object string2typecode Returns the hash code for the two, three or four names of inclusion atom types str2typeindex Returns the type index for the given pair of exclusion atom type names writeatommap Writes the encoded map for the given Atom Map object to an Atom Vector file The isAtomMap() function determines if the given object is an Atom Map and if it is, the root of the Atom Map is returned in the second argument, the atom or index number of the first atom contained in this Atom Map is returned in the third argument and the total number of atoms contained in this Atom Map is returned in the last argument. Function Name Return Type Return Value isAtomMap int whether #1 is an Atom Map Argument Type Value #1 PyObject * the subject of this query; must not be NULL! #2 PyObject ** returns the root Atom Map #3 int * returns the atom number of the first atom #4 int * returns the number of atoms contained in this Atom Map Return Value Indicate 0 #1 is not an Atom Map (or may have been an Atom Map at one time but has now been deleted) 1 #1 is an Atom Map #1 must not be NULL. Note that if #1 is an Atom (and not a Group), #4 will contain the value 0. This is not a way to determine if #1 is an Atom or a Group because #4 is also zero for an empty Group. The reference counter for #2 must be updated if you keep this pointer. An Atom Map can be determined to be a root node by comparing its pointer with the pointer returned in #2. If it is a root node then the number returned in #3 should be 0 if the Atom Map has been properly indexed. Return to Index The readatommap() function reads the encoded map from the given Atom Vector file (AVF), then compares the encoded map with the encoded map of the given Atom Map. The AVF must be positioned at the start of the map section before calling this function. Function Name Return Type Return Value readatommap int 0 for a match, non-zero for errors or mismatch Argument Type Value #1 PyObject * the subject of this query; must not be NULL! #2 FILE * pointer to the AVF, positioned at the start of the map section Return Value Indicate -6 could not encode the map for #1 -5 could not read the encoded map in the AVF -4 could not allocate memory for the map -3 could not read the string length field -1 or -2 #1 is not an Atom Map or has been deleted 0 the maps match 1 the maps do not match #1 must not be NULL. When the maps do not match then the AVF is almost certainly not appropriate for the given Atom Map. If the maps match, it is highly probable that the AVF contains data previously generated for the given Atom Map. Note the return value is 0 for success. Non-zero return values indicate mismatch or errors. Return to Index The writeatommap() function encodes the map for the given Atom Map then writes it to the opened Atom Vector file. The file header must already be written and the file is positioned at the start of the map section. Function Name Return Type Return Value writeatommap int 0 indicate success Argument Type Value #1 PyObject * the subject of this action; must not be NULL! #2 FILE * pointer to the opened Atom Vector file Return Value Indicate 0 success -1 or -2 #1 is not an Atom Map or may have been deleted -3 the atom map could not be encoded for whatever reason Note that success is indicated by a return value of 0. Non-zero return values indicate failure. Return to Index The mapfromavf() function reads the encoded map from the Atom Vector file (AVF), decodes the map to create a new Atom Map and returns a pointer to the map. The AVF must be positioned at the start of the encoded map. The caller is responsible for deallocating memory for the new Atom Map. Function Name Return Type Return Value mapfromavf PyObject * pointer to the newly created Atom Map Argument Type Value #1 const char * the location of a force field parameter directory #2 size_t the length of the encoded map #3 int the number of atoms encoded by the map #4 FILE * pointer to the opened AVF Return Value Indicate not NULL success NULL One of: cannot allocate memory for the encoded map; could not read the encoded map from the AVF; cannot create the new Atom Map; could not decode the map; number of atoms in the decoded map did not match the number declared in #3. Note that this function binds the newly created Atom Map to a force parameter directory but no parameters are assigned yet. When parameters are assigned later, these have to come from the force parameter directory specified in #1. Return to Index The atomnumber() function returns the atom (index) number for the given Atom Map. If an atom number cannot be determined for the Atom Map, the return value is negative which is illegal for an atom index. Function Name Return Type Return Value atomnumber int the atom number for #1 or an error code Argument Type Value #1 PyObject * the subject of the query Return Value Indicate 0 or positive the atom number -1 #1 is not an Atom but a Group Atom Map -2 or -3 #1 is not an Atom Map or has been deleted -4 #1 is NULL The return value is a valid atom number if it is at least 0 or a positive number. A negative number is an indication of failure. Return to Index The refnumber() function returns the reference number for the given Atom Map. If a reference number cannot be determined for the Atom Map, the return value is negative which is illegal for a reference number. Function Name Return Type Return Value refnumber int the reference number for #1 or an error code Argument Type Value #1 PyObject * the subject of the query Return Value Indicate 0 or positive the atom reference number -1 #1 is a not an Atom but a Group Atom Map -2 or -3 #1 is not an Atom Map or has been deleted -4 #1 is NULL Return to Index The fpflocation() function returns a string containing the location of the force parameter directory for the given Atom Map. Function Name Return Type Return Value fpflocation char * location of the force parameter directory Argument Type Value #1 PyObject * the subject of the query; must not be NULL! Return Value Indicate not NULL pathname of a force parameter directory NULL #1 is not an Atom Map or may have been deleted Return to Index The maps2typecode() function takes the inclusion atom types for the given two, three or four Atom Maps, hash the two, three or four atom types into a numeric code, returns the code in the first argument and returns a success code. Function Name Return Type Return Value maps2typecode int greater than 0 if a type code has been generated Argument Type Value #1 unsigned long * the type code is returned here #2 PyObject * the first Atom Map, must not be NULL #3 PyObject * the second Atom Map, must not be NULL #4 PyObject * the third Atom Map, or NULL #5 PyObject * the fourth Atom Map, or NULL Return Value Indicate 1 #1 contains a type code 0 one or more Atom Maps have null inclusion atom types -1 one or more Atom Maps have unassigned inclusion atom types -2 #2 or #3 is NULL -3 or -4 #2 is not an Atom Map or has been deleted -5 #2 is a Group and not an Atom -6 or -7 #3 is not an Atom Map or has been deleted -8 #3 is a Group and not an Atom -9 #3 is an alien Atom Map -10 or -11 #4 is not an Atom Map or has been deleted -12 #4 is a Group and not an Atom -13 #4 is an alien Atom Map -14 or -15 #5 is not an Atom Map or has been deleted -16 #5 is a Group and not an Atom -17 #5 is an alien Atom Map Return to Index The string2typecode() function takes the two, three or four atom inclusion type names provided, convert them to numeric codes and hash them into a unique number. Function Name Return Type Return Value string2typecode int greater than 0 if a type code has been generated Argument Type Value #1 unsigned long * the type code is returned here #2 PyObject * use the atom inclusion type dictionary for this Atom Map #3 const char * the first atom inclusion type name, must not be NULL #4 const char * the second atom inclusion type name, must not be NULL #5 const char * the third atom inclusion type name, or NULL #6 const char * the fourth atom inclusion type name, or NULL Return Value Indicate 1 #1 contains a type code 0 one or more inclusion atom type names are blank strings -1 one or more inclusion atom type names are unknown -2 or -3 #2 is not an Atom Map or has been deleted -4 #3 or #4 is NULL #3 and #4 must not be NULL pointers but may be null strings. The Atom Map specified in #2 provides the dictionary of known atom inclusion types; any node of the map may be specified. Return to Index The str2typeindex() function converts a type string to a type index. The type string consists of two atom exclusion type names separated by a colon and the pair of names are enclosed by two more colons. The type index is a hash of the two type codes represented by the names. The same hash is produced regardless of the order of the names. Function Name Return Type Return Value str2typeindex int greater than 0 if a type code has been generated Argument Type Value #1 PyObject * use the atom exclusion type dictionary for this Atom Map #2 char * the first atom inclusion type name, must not be NULL Return Value Indicate 0 or positive a legal type index -1 #1 is not an Atom Map -2 the type string did not start with a colon -3 the type string was incomplete or had illegal characters -4 there was extraneous text after the type string -5 the first type was NULL or unknown -6 the second type was NULL or not unknown This function modifies the type string in #2: the second and third colons are replaced by the null character. The Atom Map specified in #1 provides the dictionary of known atom exclusion types; any node of the map may be specified. Return to Index The excltypelist() function takes a given Atom Map, locates the root, forms and returns a list containing the atom exclusion type code for all the atoms. If there is an error a NULL pointer is returned. The caller is responsible for deallocating memory for the list. Function Name Return Type Return Value excltypelist int * pointer to the list of atom exclusion type codes Argument Type Value #1 PyObject * a node of the Atom Map for which the type list is desired Return Value Indicate not NULL pointer to the type list NULL One of: #1 is not an Atom Map; no memory for the type list; not all atoms have been assigned atom exclusion types Legal values for the type code are 0 and positive numbers. A null atom exclusion type corresponds to a type code of -1. This is the only negative number that can be found in a type code list. #1 may be any node of an Atom Map, the returned type list is for the atoms in the entire map. Return to Index The atomproplist() function returns a list of atom properties for all atoms in the given Atom Map. (There is no attempt to go to the root of the Atom Map.) The caller is responsible for deallocating memory for these lists. Function Name Return Type Return Value atomproplist int greater than 0 if a type code has been generated Argument Type Value #1 PyObject * the source Atom Map #2 int number of atoms #3 double * list containing the requested atom properties #4 int if 'C', the atom property is atomic charge, if 'W' the atom property is the inverse mass. Return Value Indicate 1 #3 contains the requested list -1 #1 is not an Atom Map or has been deleted -2 the number of atoms contained in #1 does not match the number declared in #2 -3 the property table is not completely filled -4 #4 is not 'C' or 'W' Note that with the return value of -3, the property list has been created and the caller should deallocate the list. Return to Index Intro Top Group Atom Data Print String Compare Methods Mapping Example