MDX Tutorial
Adding a Feature To "NAMD-lite"
The main MDX application is MDSim, which is a linked combination of the mdsim front end to the mdapi interface layer communicating with the deven engine, as shown in the diagram. The deven library is actually a manager that calls the force, step, and mgrid libraries. For many common cases, it is easy to extend the capabilities of the engine without having to make any changes to mdsim or to comprehend details of the MDAPI Specification (PDF). The following demonstration adds the computation of linear momentum as a feature to the MDSim application and returns this value as a "result".
The MDAPI provides the convention that the engine defines a type "Param" that presents simulation parameters to the front end that should be set before running a simulation. Similarly, the engine also defines a type "Result" that provides results of the simulation back to the front end, generally consisting of reductions such as potential energies and temperatures.
Within deven,
the "Result" type is a C struct (struct Result_tag)
that is defined in the file
deven/result.h.
Add to this as its last field:
MD_Dvec linmo;
that will be used to store the computed linear momentum. The revised result.h file is provided.
There is an MDAPI convention for the engine to
provide its defined "Result" type to the front end.
This convention requires that the contents of the "Result"
structure be fully specified and names be associated with each
of the fields.
The contents are provided by the resultMemberList[]
in file
deven/deven.c.
The entries to this need to correspond precisely to the entries
in struct Result_tag.
Note that the entries labeled "pe" through "bound" must be in that
stated order, corresponding to the internals of
the ForceEnergy type.
Add to resultMemberList[] the line:
{ MD_DVEC, 1, "linmo" }, /* linear momentum */
so that it corresponds to your earlier change to
struct Result_tag.
This entry provides, respectively, the type number
as defined by the MDAPI, the number of this type represented
(in this case "1" refers to a single variable as opposed to an array),
and finally the name "linmo" to be used for this field.
The revised deven.c file is
provided.
Finally, we need code to actually compute the linear momentum.
The reductions for the system are determined within the
reductions() function within the
deven/run.c file.
Within the declarations section of this function,
include the following code:
/* needed to compute linear momentum */
MD_Dvec accum = { 0.0, 0.0, 0.0 };
StepParam *step_param = &(e->step_param);
MD_Atom *atom = step_param->atom;
MD_Dvec *vel = step_system->vel;
int32 natoms = step_param->natoms;
int32 i;
Somewhere after the declarations, also include within this function the following code to compute the linear momentum and assign it to the
linmo field of struct Result_tag:
/* compute linear momentum */
for (i = 0; i < natoms; i++) {
accum.x += atom[i].m * vel[i].x;
accum.y += atom[i].m * vel[i].y;
accum.z += atom[i].m * vel[i].z;
}
result->linmo = accum;
The revised run.c file is provided.
It turns out that these are the only code changes that need to be made
in order to enable this particular "result" for MDSim.
Compile these code modifications for deven by performing
within src/deven/ directory:
$ make
If you have MDX installed, you will also need to change to the base MDX directory and perform:
$ make install
Also make sure to recompile mdsim if you are linking deven as a static library. The mdsim front end interacts with the MDAPI interface in such a way that it will automatically allow the logical extension to the config file language. Test it by adding the following line to
demo/alanin.config:
results linmo
and then changing to the
demo/ directory and running:
$ mdsim alanin.config
where you might have to also specify the path to the
mdsim
executable.
Notice that the results that are produced now include three more
columns:
linmo_x, linmo_y, linmo_z.
These values are approximately zero, up to round-off error,
because center-of-mass motion was not allowed.
A better demonstration of the conservation of linear momentum
is shown by also setting
COMmotion yes
to allow center-of-mass motion; now re-running the simulation reveals that the most significant digits of each linear momentum component do remain constant.
To shortcut the file editing involved in the discussion above
download the file
linmo.tar.gz
into the MDX base directory
and perform the following:
$ tar xvzf linmo.tar.gz
Then recompile
src/deven,
recompile src/mdsim if necessary,
reinstall if necessary,
and then change to the demo/ directory
and perform:
$ mdsim alanin.linmo.config
to demonstrate conservation of linear momentum.
Modification to the simulation parameters are done similarly.
For deven, you would need to change the
struct Param_tag
definition in the file
deven/param.h
and make corresponding changes to
paramMemberList[]
in the file
deven/deven.c.
Supposing that a "Param" member named "foo" is added,
this automatically enables extension of the config file language:
foo = bar
deven_update() function in file
update.c as to how that "Param" setting
will affect the simulation.
Note that the original deven did not perform any computation itself. Instead it acted as a manager for the force, step, and mgrid libraries. A more elegant, although slightly longer, solution would have been to perform the computation of linear momentum within the step library.
