Edited documentation

agl/CMakeLists.txt

@@ -1,7 +1,8 @@
 cmake_minimum_required (VERSION 2.8)
 
-cmake_policy(SET CMP0011 NEW)
 cmake_policy(SET CMP0003 OLD)
+cmake_policy(SET CMP0011 NEW)
+cmake_policy(SET CMP0015 NEW)
 
 # set project name
 set (PROJECT agl)
@@ -28,4 +29,4 @@ set (LIBRARIES)
 set (TARGETS "")
 set (HEADERS "")
 
-add_subdirectory (src)
+add_subdirectory (${${PROJECT}_SOURCE_DIR})

agl/README

@@ -0,0 +1,15 @@
+agl - program that creates PDB file with chosen aglomerate
+Version: 1.0.1
+License: GPL
+
+Usage:
+  agl -a FILENAME -i FILENAME -c X,Y,Z -o FILEMANE [ -l LOGFILE] [ -q ] [ -h ]
+
+Parametrs:
+  -a          - input file with aglomerates (in format statgen)
+  -i          - input file with coordinates
+  -c          - cell size (float), A
+  -o          - output file with coordinates
+  -l          - log enable
+  -q          - quiet enable
+  -h          - show this help and exit

agl/about.dox

@@ -0,0 +1,63 @@
+/*! 
+ * @mainpage agl
+ * @image latex ./logo.png
+ *
+ * @section intro_sec Introduction
+ *
+ * <b>About this program</b>:
+ * <ul>
+ * <li>Program that creates PDB file with chosen aglomerate
+ * </ul>
+ *
+ * <b>Developer</b>:
+ * <ul>
+ * <li>Evgeniy Alekseev aka arcanis <pre><esalexeev (at) gmail (dot) com></pre>
+ *</ul>
+ * <b>License</b>:
+ * <ul>
+ * <li>GPL
+ * </ul>
+ *
+ * @section How-To-Use How to use
+ * Usage:
+ * <pre>
+ * agl -a FILENAME -i FILENAME -c X,Y,Z -o FILEMANE [ -l LOGFILE] [ -q ] [ -h ]
+ *
+ * Parametrs:
+ *    -a          - input file with aglomerates (in format statgen)
+ *    -i          - input file with coordinates
+ *    -c          - cell size (float), A
+ *    -o          - output file with coordinates
+ *    -l          - log enable
+ *    -q          - quiet enable
+ *    -h          - show this help and exit
+ * </pre>
+ * 
+ * @page Install
+ * 
+ * @section Requirements Requirements
+ * The application statgen requires the following external stuff:
+ * - cmake  >= 2.8
+ * - gcc    >= 4.8
+ *
+ * @section How-To How to install
+ *
+ * @subsection Linux Linux
+ * @code
+ * mkdir build && cd build
+ * cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release ../
+ * make
+ * make install
+ * @endcode
+ * 
+ * @subsection Windows Windows
+ * @code
+ * create project file using 'cmake'
+ * compile project
+ * @endcode
+ * You may also download compiled executable file for Win_x86.
+ *
+ * @page Changelog
+ * V.1.0.1 (2013-07-27)
+ * * initial release
+ */ 

agl/agl.cmake

@@ -1,22 +1,32 @@
 # set directories
 set (${PROJECT}_BINARY_DIR bin)
-set (${PROJECT}_SOURCE_DIR src:include)
+set (${PROJECT}_SOURCE_DIR src)
+set (${PROJECT}_INCLUDE_DIR include)
 set (${PROJECT}_LIB_DIR lib)
 
-set (CMAKE_INCLUDE_PATH ${${PROJECT}_SOURCE_DIR})
-set (CMAKE_LIBRARY_PATH ${${PROJECT}_LIB_DIR})
+# include_path
+include_directories (${${PROJECT}_INCLUDE_DIR}/${PROJECT}
+                     ${${PROJECT}_SOURCE_DIR})
+# library path
+link_directories (${${PROJECT}_LIB_DIR})
+# executable path
 set (EXECUTABLE_OUTPUT_PATH ${${PROJECT}_BINARY_DIR})
+
+# verbose
 set (CMAKE_VERBOSE_MAKEFILE ON)
 
+# flags
 if ( WITH_DEBUG_MODE )
-  ADD_DEFINITIONS ( -DDEBUG_MODE=1 )
+  add_definitions ( -DDEBUG_MODE=1 )
 endif ()
-
 if ( CMAKE_COMPILER_IS_GNUCXX )
   set (ADD_CXX_FLAGS  "-Wall")
   set (CMAKE_CXX_FLAGS "-O0 ${ADD_CXX_FLAGS}")
   set (CMAKE_CXX_FLAGS_DEBUG "-g -O0")
   set (CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG")
+elseif ( MSVC )
+  set (ADD_CXX_FLAGS  "/W4")
+  set (CMAKE_CXX_FLAGS "${ADD_CXX_FLAGS}")
 else ()
-  message (STATUS "Flags not enabled")
+  message ("Unknown compiler")
 endif ()

agl/src/CMakeLists.txt

@@ -3,59 +3,27 @@ set ("${PROJECT}_VERSION_MINOR" 0)
 set ("${PROJECT}_VERSION_PATCH" 1)
 set ("${PROJECT}_VERSION" ${${PROJECT}_VERSION_MAJOR}.${${PROJECT}_VERSION_MINOR}.${${PROJECT}_VERSION_PATCH})
 
-message (STATUS ${${PROJECT}_VERSION})
+message (STATUS "${PROJECT}: Version ${${PROJECT}_VERSION}")
 
-## set files
-# main files
-set (MAIN_SOURCES main)
-# not public srcs
-set (PRIVATE_CLASSES)
-# headers only files
-SET (HEADERS_ONLY)
-# public srcs
-set (PUBLIC_CLASSES add_main 
-                    coords 
-                    envir_search 
-                    messages 
-                    print_struct 
-                    set_center)
-# public headers
-set (PUBLIC_HEADERS)
-# shared libraries
+# set files
+aux_source_directory (. SOURCES)
+
+# set library
 if (CMAKE_COMPILER_IS_GNUCXX)
   set (ADDITIONAL_LIB m)
 else ()
   set (ADDITIONAL_LIB)
 endif()
-set (SOURCES)
-
-# append list
-foreach (class ${PRIVATE_CLASSES})
-  LIST (APPEND SOURCES ${class}.c)
-  LIST (APPEND HEADERS ${class}.h)
-endforeach ()
-
-foreach (class ${HEADERS_ONLY})
-  LIST (APPEND HEADERS ${class}.h)
-endforeach ()
-
-foreach (class ${PUBLIC_CLASSES})
-  LIST (APPEND SOURCES ${class}.c)
-  LIST (APPEND HEADERS ../include/${PROJECT}/${class}.h)
-  LIST (APPEND PUBLIC_HEADERS ../include/${PROJECT}/${class}.h)
-endforeach ()
 
 # message
 message (STATUS "SOURCES: ${SOURCES}")
 
 # link libraries and compile
-add_executable (${PROJECT} ${MAIN_SOURCES} ${SOURCES})
+add_executable (${PROJECT} ${SOURCES})
 target_link_libraries (${PROJECT} ${ADDITIONAL_LIB})
 
 # install properties
-INSTALL (TARGETS ${PROJECT} 
-         DESTINATION bin)
+INSTALL (TARGETS ${PROJECT} DESTINATION bin)
 if (ADD_INCLUDE)
-  INSTALL (FILES ${PUBLIC_HEADERS} 
-           DESTINATION include/${PROJECT})
+  INSTALL (FILES ${PUBLIC_HEADERS} DESTINATION include/${PROJECT})
 endif ()

agl/src/coords.c

@@ -1,52 +1,67 @@
-/* Library for reading coordinates from input file
- * 
- * Usage:
- *                    reading_coords (mode, filename, type_interaction, labels, 
- *            cell, &number_of_molecules, &number_of_atoms, true_label_molecule, 
- *                          label_molecule, type_atoms, coords, char_type_atoms)
+/**
+ * @file
  */
 
 #include <stdio.h>
 #include <stdlib.h>
 
-
+/**
+ * @fn reading_coords
+ */
 int reading_coords (const int mode, const char *filename, const int type_inter, 
                     const int *label_atom, const float *cell, int *num_mol, 
                     int *num_atoms, int *true_label_mol, int *label_mol, 
                     int *type_atoms, float *coords, char *ch_type_atoms)
-/* filename         - name of file with coordinates
- * type_inter       - type interaction (number of molecules for interaction) 
- *                    (number of molecules in aglomerate for agl)
- * label_atom       - types of atom for interaction 
- *                    (molecules in aglomerate for agl)
- * cell             - cell dimension
- * num_mol          - number of molecules for writing coordinates
- * num_atoms        - number of atoms for writing coordinates
- * true_label_mol   - massive of true numbers of molecule for atoms
- * label_mol        - massive of numbers of molecule for atoms
- * type_atoms       - massive of atom types for atoms
- * coords           - massive of coordinates
- * ch_type_atoms    - massive of char types for atoms
+/**
+ * @brief function that reads coordinates from special file format
+ * @code
+ * reading_coords (0, filename, type_inter, label_atom, cell, &num_mol, &num_atoms, 
+ *                 true_label_mol, label_mol, type_atoms, coords, ch_type_atoms);
+ * @endcode
+ * 
+ * @param mode            mode of reading; '1' is statgen, '2' is envir or 
+ *                        frad, '3' is agl
+ * @param filename        input file name
+ * @param type_inter      number of needed atoms
+ *                        (number of needed molecules)
+ * @param label_atom      massive of needed atom types
+ *                        (massive of needed molecules)
+ * @param cell            massive of cell size
+ * @param num_mol         number of molecules
+ * @param num_atoms       number of atoms
+ * @param true_label_mol  massive of true numbers of molecule for atoms
+ * @param label_mol       massive of numbers of molecule for atoms
+ * @param type_atoms      massive of atom types
+ * @param coords          massive of coordinates
+ * @param ch_type_atoms   massive of char atom types
+ * 
+ * @return 1              - file $filename does not exist
+ * @return 2              - unknown mode
+ * @return 0              - exit without errors
  */
 {
   char at_symb[32], file_string[256];
   int atoms, cur_at_num, cur_at_type, cur_mol, i, j, tr_num_atoms, ref_mol, x, y;
   float cur_coords[3], *not_tr_coords, ref[3];
   FILE *inp;
-/* cur_*, at_symb   - temp variables
- * file_string      - temp string variable
- * atoms            - total number of atoms in system
- * tr_num_atoms     - number of translated atoms for writing coordinates (m.b. 8*num_atoms)
- * ref_mol          - number of molecule for reference
- * not_tr_coords    - not translated coordinates
- * ref              - coordinates of reference molecule
- * inp              - file with input data
+  
+/* cur_*                  temp variables
+ * at_symb                temp variable
+ * file_string            temp string variable
+ * atoms                  total number of atoms in system
+ * tr_num_atoms           number of translated atoms (must be 8*num_atoms)
+ * ref_mol                number of molecule for reference in translation
+ * not_tr_coords          massive of not translated coordinates
+ * ref                    massive of coordinates of reference molecule
+ * inp                    input file
  */
   
+/// <b>Work blocks</b>
+  
   *num_atoms = 0;
   *num_mol = 0;
   
-//   Reading file
+/// <pre>   reading file </pre>
   inp = fopen (filename, "r");
   if (inp == NULL)
     return 1;
@@ -61,10 +76,11 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     sscanf (file_string, "%i%s%f%f%f%i%i", &cur_at_num, at_symb, &cur_coords[0], 
             &cur_coords[1], &cur_coords[2], &cur_at_type, &cur_mol);
     
+// reading variables according to selected mode
     switch (mode)
     {
       case 0:
-//         for statgen
+// mode == 0 (selected atoms)
         for (j=0; j<type_inter; j++)
           if (cur_at_type == label_atom[j])
           {
@@ -85,7 +101,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
           }
         break;
       case 1:
-//         for envir and frad
+// mode == 1 (all atoms)
         not_tr_coords[3**num_atoms+0] = cur_coords[0];
         not_tr_coords[3**num_atoms+1] = cur_coords[1];
         not_tr_coords[3**num_atoms+2] = cur_coords[2];
@@ -104,7 +120,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
         *num_atoms = *num_atoms + 1;
         break;
       case 2:
-//         for agl
+// mode == 2 (selected molecules)
         for (j=0; j<type_inter; j++)
           if (cur_mol == label_atom[j])
           {
@@ -126,18 +142,18 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
             *num_atoms = *num_atoms + 1;
           }
         break;
-      default: return 1;
+      default: return 2;
     }
   }
   fclose (inp);
   
-//   Translation
+/// <pre>   translation </pre>
   tr_num_atoms = *num_atoms;
   for (i=0; i<*num_atoms; i++)
     for (j=0; j<3; j++)
       coords[3*i+j] = not_tr_coords[3*i+j];
   
-//   Assign initial value to reference coordinates
+// assign initial value to reference coordinates
   ref_mol = label_mol[0];
   for (i=0; i<3; i++)
     ref[i] = coords[3*0+i];
@@ -154,7 +170,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     for (x=0; x<3; x++)
     {
       if (ref[x] >= 0.0)
-//         if xyz >= 0.0 A
+// if xyz >= 0.0 A
      {
         for (j=0; j<3; j++)
           if (j == x)
@@ -167,7 +183,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
         tr_num_atoms++;
       }
       else
-//         if xyz < 0.0 A
+// if xyz < 0.0 A
       {
         for (j=0; j<3; j++)
           if (j == x)
@@ -186,7 +202,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
       for (y=x+1; y<3; y++)
       {
         if ((ref[x] >= 0.0) && (ref[y] >= 0.0))
-//         if xyz and xyz >= 0.0 A
+// if xyz and xyz >= 0.0 A
         {
           for (j=0; j<3; j++)
             if ((j == x) || (j == y))
@@ -200,7 +216,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
         }
         
         if ((ref[x] < 0.0) && (ref[y] < 0.0))
-//         if xyz and xyz < 0.0 A
+// if xyz and xyz < 0.0 A
         {
           for (j=0; j<3; j++)
             if ((j == x) || (j == y))
@@ -216,7 +232,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
       
       for (y=0; y<3; y++)
         if ((ref[x] < 0.0) && (ref[y] >= 0.0))
-//           if xyz OR xyz >= 0.0
+// if xyz OR xyz >= 0.0
         {
           for (j=0; j<3; j++)
           {
@@ -235,7 +251,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
     
     if ((ref[0] >= 0.0) && (ref[1] >= 0.0) && (ref[2] >= 0.0))
-//       if x and y and z >= 0.0 A
+// if x and y and z >= 0.0 A
     {
       coords[3*tr_num_atoms+0] = not_tr_coords[3*i+0] - cell[0];
       coords[3*tr_num_atoms+1] = not_tr_coords[3*i+1] - cell[1];
@@ -247,7 +263,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
     
     if ((ref[0] >= 0.0) && (ref[1] >= 0.0) && (ref[2] < 0.0))
-//       if x and y >= 0.0 A and z < 0.0 A
+// if x and y >= 0.0 A and z < 0.0 A
     {
       coords[3*tr_num_atoms+0] = not_tr_coords[3*i+0] - cell[0];
       coords[3*tr_num_atoms+1] = not_tr_coords[3*i+1] - cell[1];
@@ -259,7 +275,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
     
     if ((ref[0] >= 0.0) && (ref[1] < 0.0) && (ref[2] >= 0.0))
-//       if x and z >= 0.0 A and y < 0.0 A
+// if x and z >= 0.0 A and y < 0.0 A
     {
       coords[3*tr_num_atoms+0] = not_tr_coords[3*i+0] - cell[0];
       coords[3*tr_num_atoms+1] = not_tr_coords[3*i+1] + cell[1];
@@ -271,7 +287,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
     
     if ((ref[0] < 0.0) && (ref[1] >= 0.0) && (ref[2] >= 0.0))
-//       if y and z >= 0.0 A and x < 0.0 A
+// if y and z >= 0.0 A and x < 0.0 A
     {
       coords[3*tr_num_atoms+0] = not_tr_coords[3*i+0] + cell[0];
       coords[3*tr_num_atoms+1] = not_tr_coords[3*i+1] - cell[1];
@@ -283,7 +299,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
     
     if ((ref[0] < 0.0) && (ref[1] < 0.0) && (ref[2] >= 0.0))
-//       if x and y < 0.0 A and z >= 0.0 A
+// if x and y < 0.0 A and z >= 0.0 A
     {
       coords[3*tr_num_atoms+0] = not_tr_coords[3*i+0] + cell[0];
       coords[3*tr_num_atoms+1] = not_tr_coords[3*i+1] + cell[1];
@@ -295,7 +311,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
     
     if ((ref[0] < 0.0) && (ref[1] >= 0.0) && (ref[2] < 0.0))
-//       if x and z < 0.0 A and y >= 0.0 A
+// if x and z < 0.0 A and y >= 0.0 A
     {
       coords[3*tr_num_atoms+0] = not_tr_coords[3*i+0] + cell[0];
       coords[3*tr_num_atoms+1] = not_tr_coords[3*i+1] - cell[1];
@@ -307,7 +323,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
     
     if ((ref[0] >= 0.0) && (ref[1] < 0.0) && (ref[2] < 0.0))
-//       if x >= 0.0 A and y and z < 0.0 A
+// if x >= 0.0 A and y and z < 0.0 A
     {
       coords[3*tr_num_atoms+0] = not_tr_coords[3*i+0] - cell[0];
       coords[3*tr_num_atoms+1] = not_tr_coords[3*i+1] + cell[1];
@@ -319,7 +335,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
     
     if ((ref[0] < 0.0) && (ref[1] < 0.0) && (ref[2] < 0.0))
-//       if x and y and z < 0.0 A
+// if x and y and z < 0.0 A
     {
       coords[3*tr_num_atoms+0] = not_tr_coords[3*i+0] + cell[0];
       coords[3*tr_num_atoms+1] = not_tr_coords[3*i+1] + cell[1];
@@ -331,7 +347,7 @@ int reading_coords (const int mode, const char *filename, const int type_inter,
     }
   }
   
-//   free memory
+/// <pre>   free memory </pre>
   free (not_tr_coords);
   
   return 0;

agl/src/main.c

@@ -46,7 +46,7 @@ int main(int argc, char *argv[])
     if ((argv[i][0] == '-') && (argv[i][1] == 'h'))
     {
       sprintf (tmp_str, "                                        agl\n");
-      sprintf (tmp_str, "%sProgram for create PDB file with choosen aglomerate\n", tmp_str);
+      sprintf (tmp_str, "%sProgram for create PDB file with chosen aglomerate\n", tmp_str);
       sprintf (tmp_str, "%sVersion : 1.0.1                                                    License : GPL\n", tmp_str);
       sprintf (tmp_str, "%s                                                    Evgeniy Alekseev aka arcanis\n", tmp_str);
       sprintf (tmp_str, "%s                                                    E-mail : esalexeev@gmail.com\n\n", tmp_str);

agl/src/messages.c

@@ -1,16 +1,27 @@
-/* Library for printing messages at output
- *
- * Usage:
- *                                             message (log, mode, text, output)
+/**
+ * @file
  */
 
 #include <stdio.h>
 #include <time.h>
 
 
+/**
+ * @fn message
+ */
 int message (const int log, const int mode, const char *text, FILE *output)
-/* mode             - number of message
- * text             - additional text
+/**
+ * @brief function that prints messages to output
+ * @code
+ * message (log, mode, text, output);
+ * @endcode
+ * 
+ * @param log             equal to 1 if print to logfile
+ * @param mode            number of message
+ * @param text            additional text
+ * @param output          output file (may be stdout)
+ * 
+ * @return 0              - exit without errors
  */
 {
   char out[4096];
@@ -18,6 +29,7 @@ int message (const int log, const int mode, const char *text, FILE *output)
   if (log == 1)
   {
     char time_str[256];
+    
     time_t t = time (NULL);
     struct tm* aTm = localtime (&t);
     sprintf (time_str, "[%04d-%02d-%02d %02d:%02d:%02d] [%2i]: ", aTm->tm_year+1900, 

agl/src/print_struct.c

@@ -1,3 +1,7 @@
+/**
+ * @file
+ */
+
 /* Library for printing structure to pdb file
  * 
  * Usage:
@@ -8,23 +12,37 @@
 #include <stdio.h>
 
 
+/**
+ * @fn print_structure
+ */
 int print_structure (const char *output, const int num_needed_mol, const int *needed_mol, 
                      const int num_atoms, const int *label_mol, const char *ch_type_atoms, 
                      const float *coords)
-/* output           - output file name
- * num_needed_mol   - number of needed molecules
- * needed_mol       - massive of needed molecules
- * num_atoms        - number of atoms
- * label_mol        - massive of numbers of molecule for atoms
- * ch_type_atoms    - massive of char types for atoms
- * coords           - massive of coordinates
+/**
+ * @brief function that prints structure to pdb file
+ * @code
+ * print_structure (output, num_needed_mol, needed_mol, num_atoms, label_mol, 
+ *                  char_type_atoms, coords);
+ * @endcode
+ * 
+ * @param output          output file name
+ * @param num_needed_mol  number of needed molecules
+ * @param needed_mol      massive of number of needed molecules
+ * @param num_atoms       number of atoms
+ * @param label_mol       massive of numbers of molecule for atoms
+ * @param ch_type_atoms   massive of char atom types
+ * @param coords          massive of coordinates
+ * 
+ * @return 0              - exit without errors
  */
 {
   int cur_atom, cur_atom_num, cur_mol, i, j;
   FILE *f_out;
-/* cur_atom         - current atom
- * cur_atom_num     - true atom number
- * cur_mol          - current molecule
+  
+/* cur_atom               current atom
+ * cur_atom_num           true atom number
+ * cur_mol                current molecule
+ * f_out                  output file
  */
   
   cur_atom = 1;