Coding week 2012

In the week of January 9-13 2012 we will have an coding week at ICP in Stuttgart.

Python interface
Create a python interface for. In a first stage, it is only important to directly translate the Tcl interface commands to Python. Improvements on the interface to make it more Pythonic (e.g. by using classes and NumPy) can be done later.

For the priorities in what order the different commands are to be translated, see below.

Substeps

 * 1) Separate the Tcl interface from the core code, put the Tcl parser functions into separate files
 * 2) Check which #include directives can be removed from the Tcl interface files
 * 3) Create a very simple Python interface to call the functions

Improvements on the Verlet lists
Currently, there is a single cutoff radius. Whenever two particles are within this radius, the pair is added to the Verlet list. When the system contains particles of a very different size (e.g. colloids in water), this results in far too many particle pairs. It should be possible to modify the Verlet list update such that only those pairs that are within the cutoff radius of a specific interaction are taken into account.

Clean up nonbonded interactions
This task has two subtasks:
 * At the moment, all interactions are defined in header files to allow for inlining. However, this does not reallt speed up the simulations, but it does make compilation slower and code handling nastier. Therefore, all interactions shall be split into header and source file.
 * Even when they are not used or when particles are not within the cutoff radius, some of the interactions seem to do some unnecessary computations. This shall be cleaned up.

Use the MPI cartesian communicator
At the moment, the mapping of MPI task to domain in the domain decomposition scheme is done manually. MPI provides cartesian communicators that provide a mapping for this kind of task. On some platforms, the MPI implementations can very much profit from this, therefore it would be a good idea to change to using MPI cartesian communicators in the domain decomposition.

Switch build system to cmake
The build system is to be switched from GNU Autotools to cmake. C. Junghans will prepare the Cmake build system for the coding week. CMake contains information on ESPResSo cmake.

Reorganize particles
Currently, the particles are stored as an array of structs (i.e. an array of the particle data structure).

If the particles would be stored as a struct of arrays instead, this possibly has a number of advantages:
 * new properties can be added dynamically (no more compile time switches for new properties!)
 * the code may be more efficient

The goal of this task is not to rewrite all code like this, as this will probably not be doable in a week. However, it might be interesting to see whether it is possible and whether it slows down the code significantly.

Create new homepage
The homepage http://espressomd.org does not look very nice, and it is not easy to find the wanted information. The task is to create a new homepage, based on wordpress. A first try can be seen at http://www.icp.uni-stuttgart.de/~olenz/wordpress.

The current progress can be seen on http://espressomd.org/wordpress.

Complete documentation
Document undocumented functions.

MEMD and LB cannot handle Verlet lists
LB can now. (OH, GR)

Clean up tabulated potentials code
defines should not be in the struct declaration, and one could use malloc to allow arbitrary length filenames. Just needs additional communication code.

Clean up ERROR_SPRINTF
Make all the messages look the same. Remove the curled braces, and add these only in the Tcl interface, as they are not required for Python. Probably also get rid of the numbers, as the codes are not really unique anymore.

Clean up reaction field code
INTER_RF reaction field is a per-particle-pair short-ranged interaction, but still handled as Coulomb, resulting in a strange cutoff behavior. Either, it works like DH as a normal Coulomb interaction, or as a normal short-ranged interaction with individual parameters.

Make switch-off cutoff -1.0
This helps to prevent calculation of forces for potentials that are off

Separating the TCL from the core

 * 1) Decide to split the foo.c file
 * 2) Mark in the wiki, that you're working on the file
 * 3) copy the foo.c and foo.h files to tcl_interface/foo_tcl.[ch]
 * 4) delete all the *tcl* functions from the original foo.[ch] files
 * 5) delete all the non-tcl functions from the the tcl_interface/foo_tcl.[ch] files
 * 6) modify the corresponding #ifndef FOO_H and #define FOO_H to FOO_TCL_H
 * 7) include tcl_interface/foo_tcl.h in the original foo.c file
 * 8) add tcl_interface/foo_tcl.[ch] files to libEspresso_core_la_SOURCES in src/Makefile.am
 * 9) check if Espresso compiles: do bootstrap, configure and make; If the tcl functions from the modified files are called from some other files, include the tcl_interface/foo_tcl.h file there
 * 10) Mark in the wiki, that you've finished splitting the file

In the following, it is priorized how important it is to implement a Python interface for the various commands. The prorities are as follows:


 * 1 Absolutely necessary.
 * 2 Should be done
 * 3 Not in the 1st stage (it's either probably not used in icp or should probably be redone in python)
 * 4 Deprecate? (Mostly, because it is undocumented and it's therefore unlikely, someone's using it)

List of split files

 * adresso (TR, done)
 * blockfile (PK done)
 * bin (TR, done)
 * binary_file (TR, done binary_file.[hc] are now obsolete/empty)
 * cells (PK, done)
 * constraints (PS, done)
 * domain_decomposition (TR, done)
 * dpd (TR, done)
 * global (TR,PK done)
 * grid (TR, done)
 * halo (TR, no tcl commands)
 * iccp3m (PS, done)
 * imd (FF, done)
 * integrate (PK, done)
 * interaction_data (GR, PK)
 * lattice (unnecessary)
 * lb (AS, done)
 * lbboundary (DR, done)
 * lj (TR, done)
 * ljangle (TR, done)
 * ljcos (TR, done)
 * ljcos2 (TR, done)
 * ljgen (TR, done)
 * maggs (FF, done)
 * magnetic_non_p3m_methods (TR)
 * metadynamics (PS, done)
 * mmm1d (PK, done)
 * mmm2d (PS, done)
 * nemd (PK, done)
 * p3m (TR, done, there may be problems when P3M_DEBUG is enabled (static function declaration)
 * p3m-common (TR, no tcl commands)
 * p3m-dipolar (TR, done changed static declaration)
 * particle_data (FF, done)
 * polymer (PS, done)
 * pressure (FF, done)
 * random (FF, done)
 * statistics (PK, done)
 * statistics_chain (PK, done)
 * statistics_fluid (FF, done)
 * statistics_cluster (FF, done)
 * thermostat (TR, done)
 * topology (FF, done)
 * uwerr (AS, done)
 * virtual_sites_com (FF, done)
 * tab.h (DR, done)

Commands

 * 1 cellsystem (split done)
 * 1 invalidate_system (split done)
 * 1 integrate (split done)
 * 1 setmd (split done)
 * 2 change_volume
 * 1 code_info (split done)
 * 1 part (split done)
 * 1 inter (GR: pull request sent)
 * 4 writemd (it is undocumented)
 * 4 readmd (dito)
 * 1 analyze (See below for subcommands) '''(PK partly done: main analyze parser and subcommands from statistics and statistics_chain)
 * 3 polymer (Python rewrite?) split done
 * 3 counterions (Dito) split done within polymer
 * 3 salt (Dito) split done within polymer
 * 3 velocities (Python rewrite?) split done
 * 3 maxwell_velocities (dito) split done within polymer
 * 3 crosslink done within polymer
 * 3 diamond (For the hydrogels) split done within polymer
 * 3 icosaeder (Python rewrite) split done within polymer
 * 1 imd (split done)
 * 1 t_random (split done)
 * 2 bit_random (split done)
 * 2 blockfile (split done)
 * 1 constraint (split done)
 * 2 uwerr (split done)
 * 3 nemd (split done)
 * 1 thermostat (TR done)
 * 4 bin (it is undocumented)
 * 2 lbfluid (split done)
 * 2 lbnode (CPU part done)
 * 2 lbboundary (DR done)
 * 4 replacestdchannel (it is undocumented)
 * 2 iccp3m (split done)
 * 3 adress (split done)
 * 3 update_adress_weights
 * 4 thermodynamic_force (undocumented)
 * 3 metadynamics
 * 2 lbnode_extforce (splitting within lb)
 * 2 lbprint (splitting within lb)
 * 2 cuda (split done DR)
 * 2 on_collision

Analyze Subcommands

 * 2 set (needs to be looked at in detail)
 * 2 fluid
 * 4 set_bilayer (undocumented)
 * 2 append
 * 2 push
 * 2 replace
 * 2 activate
 * 2 remove
 * 2 stored
 * 2 configs


 * 3 get_folded_positions (The only thing it does more than part print is keeping molecules together)
 * 4 modes2d (Unclear, what it does)
 * 4 bilayer_density_profile (Unclear, what it does)
 * 3 radial_density_map
 * 4 get_lipid_orients (Undocumented and probably very specialized)
 * 4 lipid_orient_order (Dito)
 * 3 mol (Functionality unknown)
 * 3 cluster_size_dist (Undocumented)
 * 2 mindist
 * 3 aggregation
 * 3 centermass
 * 3 angularmomentum
 * 4 MSD (undocumented. Probably superseeded by correlators)
 * 3 dipmom_normal
 * 3 momentofinertiamatrix
 * 3 gyration_tensor
 * 3 find_principal_axis
 * 3 nbhood
 * 3 distto
 * 4 cell_gpb (undocumented)
 * 4 Vkappa (undocumented)
 * 2 energy
 * 2 energy_kinetic
 * 2 pressure
 * 3 energy_kinetic_mol
 * 3 pressure_mol
 * 3 check_mol
 * 3 dipmom_mol
 * 2 stress_tensor
 * 2 local_stress_tensor
 * 2 p_inst
 * 2 momentum
 * 4 bins (Undocumented)
 * 4 p_IK1 (Undocumented)
 * 3 re
 * 3 
 * 3 rg
 * 3 
 * 3 rh
 * 3 
 * 3 internal_dist
 * 3 
 * 3 bond_l
 * 3 
 * 3 bond_dist
 * 3 
 * 3 g123
 * 3 
 * 3 
 * 3 
 * 3 formfactor
 * 3
 * 2 necklace (Peter needs it)
 * 3 holes
 * 3 distribution
 * 3 vel_distr
 * 2 rdf
 * 2
 * 3 
 * 3 
 * 3 rdfchain
 * 4 cwvac (Undocumented)
 * 3 structurefactor
 * 3 
 * 3 
 * 3 vanhove

Non-Bonded Interactions

 * 1 lennard-jones
 * 2 lj-gen
 * 3 lj-angle
 * 3 smooth-step
 * 3 hertzian
 * 3 bmhtf-nacl
 * 3 morse (done)
 * 2 lj-cos
 * 3 buckingham
 * 3 soft-sphere
 * 3 comforce
 * 3 lj-cos2
 * 3 comfixed
 * 3 gay-berne
 * 2 tabulated
 * 3 inter_dpd
 * 3 inter_rf
 * 3 tunable_slip
 * 3 molcut
 * 3 adress_tab_ic
 * 2 inter coulomb
 * 2 inter magnetic

Bonded interactions

 * 1 fene
 * 1 harmonic (OH done)
 * 2 subt_lj
 * 3 angle
 * 3 angledist
 * 3 dihedral
 * 3 endangledist
 * 2 tabulated
 * 3 overlapped
 * 2 rigid_bond
 * 2 virtual_bond

Constraints

 * 3 mindist_position
 * 2 wall
 * 2 sphere
 * 2 cylinder
 * 2 rhomboid
 * 2 rod
 * 2 plate
 * 3 maze
 * 2 pore
 * 2 ext_magn_field
 * 2 force
 * 2 delete

Creating New Python Commands

 * 1) Decide, what block you want to take care of. It does not need to correspond exactly to a single TCL command, but can also be a logical block (like bonds, which affetcs part and inter)
 * 2) Decide for a name for the submodule you want to write
 * 3) Find out, what could be corresponding C functions you will need, and make a good guess how difficult it will be
 * 4) Try to think of a way how to wrap it (a class, a function, a set of functions, a module)
 * 5) If it shall become part of a new module: Create a corresponding pxd and pyx file and add them to setup.py (Copy-Paste!)
 * 6) Repeat the signature of functions and data structures from the espresso core in the corresponding pyx file
 * 7) Write a Python wrapper to call these functions. Use def only and not cdef.
 * 8) Check if it builds
 * 9) Add an example to a file in the example directory. Create a new one if necessary!

Logical Sections that were already ported (and how far the porting is)

 * Global variables corresponding to setmd (a few ones are accessible, no error checking) (incomplete)
 * particle data - corresponding to part print and part pos (some are accessible, no error checking)
 * integrate ( command is available, no error checking, no documentation )
 * debye-hueckel potential (full, not documented)
 * nonbonded interactions (first conceptual implementation)
 * changeVolume (command is available, no doc)
 * invalidateSystem (command is available)

In Progress

 * globals (PK done)
 * LB (DR finished)
 * thermostat (PS, done Langevin and global options, the rest of thermostats depend on conditional compiling stuff)
 * particle properties (AS)
 * t_random, bit_random (TR) problem of conversion of c style data and python objects; many #defines
 * cells (PS)
 * pressure (DR)
 * cuda_init (DR finished)

Guidelines
We have a few coding guidelines [Here]