Commit 3e30fed7 authored by Alan O'Cais's avatar Alan O'Cais

Update example and fix some warnings

parent dc2baedd
.. _readme:
.. _readme_repo:
==============================================
The E-CAM Meso- and Multi-scale Module Library
......
.. _contributing:
.. sidebar:: General Information
.. contents:: :local:
* :ref:`search`
.. _contributing:
=======================================
How to contribute to this documentation
=======================================
......
.. _example:
.. _dipole_moments:
################################################
Analysis of charge dipole moments in DL_MESO_DPD
......@@ -26,6 +26,7 @@ Analysis of charge dipole moments in DL_MESO_DPD
Purpose of Module
_________________
This module, ``gen_dipole.f90``, is a generalization of the ``dipole.f90`` post-processing
utility of DL_MESO_DPD, the Dissipative Particle Dynamics (DPD) code from the DL_MESO_ package.
......@@ -47,8 +48,8 @@ If more than one molecular species are present, one can split :math:`\vec{P}` in
In general:
For any molecular species a file `dipole_{molecule name}` is produced, whose columns are
:math:`\textrm{snapshot index}, P_x, P_y, P_z, \sum_{i=1}^{N_{mol}}\frac{\vec{p}_i ^2}{N_{mol}},\frac{\vec{P} ^2}{V}`.
For any molecular species a file `dipole_{molecule name}` is produced, whose columns are
:math:`\textrm{snapshot index}, P_x, P_y, P_z, \sum_{i=1}^{N_{mol}}\frac{\vec{p}_i ^2}{N_{mol}},\frac{\vec{P} ^2}{V}`.
It is intended that for any quantity the contribution given *from the
species {molecule name}* is reported (i.e., the sums are restricted to
molecules of a single type).
......@@ -70,6 +71,7 @@ where :math:`l_B` is Bjerrum length.
Background Information
______________________
The base code for this module is DL_MESO_DPD, the Dissipative Particle
Dynamics code from the mesoscopic simulation package DL_MESO_,
developed by M. Seaton at Daresbury Laboratory.
......@@ -79,6 +81,7 @@ in its last released version, version 2.6 (dating November 2015).
Testing
_______
The present module ``gen_dipole.f90`` is compiled with the available Fortran90 compiler, e.g.:
``gfortran -o gen_dipole.exe gen_dipole.f90``
......@@ -99,7 +102,9 @@ Four type of beads are used with charges :math:`q_A=0.2, q_B=-1, q_C=0.6,q_D=1`;
the Bjerrum length is fixed as :math:`l_B=1`.
The bonding connections in the two molecules are pictorially given below:
::
B - A - C B - D
|
A
......@@ -119,6 +124,7 @@ and for the FIELD file
Analyzing the HISTORY file with `gen_dipole.exe`, this output is printed on the standard output
.. literalinclude:: ./out-d
The first line shows the histogram of cluster sizes: in this case,
it correctly gives 10 molecules of two beads, and 10 molecules of 4 beads.
Since internally the module checks that each molecule is a connected cluster [1]_,
......@@ -151,10 +157,13 @@ branches aligned with the cartesian axes
.. literalinclude:: ./CONFIG
where the identity of each bead is fixed by the FIELD file and is shown below
::
B(1) - A(2) - C(3) B(5) - D(6)
|
A(4)
B(1) - A(2) - C(3) B(5) - D(6)
|
A(4)
One can easily check that the dipole of each molecule is as expected:
:math:`\vec{p}_{BRANCH}=(0.04,0.32,0), \quad \vec{p}_{BD}=(0,0,-0.2)~.`
......
.. _example:
.. _history_format_DPD:
############################################
Formatting the HISTORY files of DL_MESO_DPD
......@@ -26,6 +26,7 @@ Formatting the HISTORY files of DL_MESO_DPD
Purpose of Module
_________________
This module ``format_history.f90`` is a post-processing
utility for DL_MESO_DPD, the Dissipative Particle Dynamics (DPD) code from the DL_MESO_ package.
......@@ -44,6 +45,7 @@ of trajectories.
Background Information
______________________
The base code for this module is DL_MESO_DPD, the Dissipative Particle
Dynamics code from the mesoscopic simulation package DL_MESO_,
developed by M. Seaton at Daresbury Laboratory.
......@@ -53,6 +55,7 @@ in its last released version, version 2.6 (dating November 2015).
Testing
_______
The present module is compiled with the available Fortran90 compiler, e.g.:
``gfortran -o format.exe format_history.f90``
......@@ -80,6 +83,7 @@ and the HISTORY-F file should be
Source Code
___________
.. literalinclude:: ./format_history.f90
:language: fortran
:linenos:
......
.. _example:
.. In ReStructured Text (ReST) indentation and spacing are very important (it is how ReST knows what to do with your
document). For ReST to understand what you intend and to render it correctly please to keep the structure of this
template. Make sure that any time you use ReST syntax (such as for ".. sidebar::" below), it needs to be preceded
and followed by white space (if you see warnings when this file is built they this is a common origin for problems).
####################
E-CAM example module
####################
.. sidebar:: Software Technical Information
.. Firstly, let's add technical info as a sidebar and allow text below to wrap around it. This list is a work in
progress, please help us improve it. We use *definition lists* of ReST_ to make this readable.
This list is a work in progress, please help us improve it. We use *definition lists* of ReST_ to make this readable
.. sidebar:: Software Technical Information
Language
Please indicate the main languages used by the module.
Please indicate the primary language(s) used by the module. Please also state if interfaces for other languages are
available.
Licence
Specify the licence under which the software is released.
Specify the licence under which the software is released. Provide a link to the full online description of the
licence. You'll find descriptions of the most common licences at https://opensource.org/licenses .
An example here would be: `GPL <https://opensource.org/licenses/gpl-license>`_
Documentation Tool
All source code should be documented so please indicate what tool has been used for documentation. We can help you
with Doxygen and ReST but if you use other tools it might be harder for us to help if there are problems.
All source code created for this module should be documented so please indicate what tool has been used for
documentation. Doxygen covers most languages but for Fortran you might want to use
`Ford <http://fortranwiki.org/fortran/show/FORD>`_, for Python ReST_, etc.
Application Documentation
Provide a link to any documentation.
Provide a link to any documentation for the application.
Relevant Training Material
Add a link to any relevant training material.
Add a link to any relevant training material. If there currently is none then say 'Not currently available.'
.. In the next line you have the name of how this module will be referenced in the main documentation (which you can
reference, in this case, as ":ref:`example`"). You *MUST* change the reference below from "example" to something
unique otherwise you will cause cross-referencing errors. The reference must come right before the heading for the
reference to work (so don't insert a comment between).
.. _example:
####################
E-CAM example module
####################
.. Let's add a local table of contents to help people navigate the page
.. contents:: :local:
.. contents:: :local:
.. Add an abstract for a *general* audience here. Write a few lines that explains the "helicopter view" of why you are
creating this module. For example, you might say that "This module is a stepping stone to incorporating XXXX effects
into YYYY process, which in turn should allow ZZZZ to be simulated. If successful, this could make it possible to
produce compound AAAA while avoiding expensive process BBBB and CCCC."
This is an example of what a *module* for E-CAM looks like. Please add to this template any additional items that are
straightforward to fill out in the general case. You are free add any level of complexity you wish (within the bounds of
what ReST_ can do).
This is an example of what a *module* for E-CAM looks like. The original source of this page (:download:`readme.rst`)
contains lots of additional comments to help you create your module (and understand ReST_ syntax) so please use this as
a starting point. You are free add any level of complexity you wish (within the bounds of what ReST_ can do). More
general instructions for making your contribution can be found in ":ref:`contributing`".
To add your module, fork this GitLab repository to your account on GitLab. Clone your repository, make a feature branch
and add a directory that will contain your module information. Copy this :download:`readme.rst` file there. Push your
changes back to GitLab and immediately open a merge request from your feature branch against our repository. We can
discuss your module in the merge request and help you get it accepted.
Remember that for a module to be accepted into the E-CAM repository, your source code changes in the target application
must pass a number of acceptance criteria:
.. Add technical info as a sidebar and allow text below to wrap around it
* Style *(use meaningful variable names, no global variables,...)*
* Source code documentation *(each function should be documented with each argument explained)*
* Tests *(everything you add should have either unit or regression tests)*
* Performance *(If what you introduce has a significant computational load you should make some performance optimisation
effort using an appropriate tool. You should be able to verify that your changes have not introduced unexpected
performance penalties, are threadsafe if needed,...)*
Purpose of Module
_________________
Give a brief overview of why the module is/was being created.
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
Give a brief overview of why the module is/was being created, explaining a little of the scientific background and how
it fits into the larger picture of what you want to achieve.
If needed you can include latex mathematics like
:math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}`
which won't show up on GitLab/GitHub but will in rendered documention (like if you use Sphinx).
which won't show up on GitLab/GitHub but will in final online documentation.
If you want to add a citation, such as [CIT2002]_. Note that citations may get rearranged, e.g., to the bottom of the
"page".
.. [CIT2002] A citation (as often used in journals).
Background Information
______________________
If the modifications are to an existing code base then this would be the place to describe that codebase and how to get
access to it.
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
If the modifications are to an existing code base (which is typical) then this would be the place to name that
application. List any relevant urls and explain how to get access to that code. There needs to be enough information
here so that the person reading knows where to get the source code for the application, what version this information is
relevant for, whether this requires any additional patches/plugins, etc.
Testing
_______
Overall, this module is supposed to be self-contained, but linking to specific URLs with more detailed information is
encouraged. In other words, the reader should not need to do a websearch to understand the context of this module, all
the links they need should be already in this module.
Provide the build information for the module here an explain how tests are run.
Building and Testing
____________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
Provide the build information for the module here and explain how tests are run. This needs to be adequately detailed,
explaining if necessary any deviations from the normal build procedure of the application (and links to information
about the normal build process needs to be provided).
Source Code
___________
Here link the source code that was created for the module. In this example I'm using a patch file for that reason I need
to explain what code (including exact version information), the source code is for.
.. Notice the syntax of a URL reference below `Text <URL>`_
Here link the source code *that was created for the module*. If you are using Github or GitLab and the `Gitflow Workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow>`_ you can point to your feature branch.
Linking to your pull/merge requests is even better. Otherwise you can link to the explicit commits. In this example I'm
using a patch file to highlight my source code changes, for that reason I need to explain what code (including exact
version information), the source code is for.
You can create the patch file by (for example if you are using git for your version control) making your changes for the
module in a feature branch and then doing something like the following:
You can create a similar patch file by (for example if you are using git for your version control) making your changes
for the module in a feature branch and then doing something like the following:
.. Don't forget the white space around the "literal block" (a literal block keeps all spacing and is a good way to
include terminal output, file contents, etc.)
::
......@@ -86,14 +145,18 @@ module in a feature branch and then doing something like the following:
0001-My-squashed-commits.patch
To include a patch file do something like the following:
To include a patch file do something like the following (take a look at the source code of this document to see the
syntax required to get this):
.. Below I am telling Sphinx that the included file is C code, if possible it will then do syntax highlighting. I can
even emphasise partiuclar lines (here 2 and 9-11)
.. literalinclude:: ./simple.patch
:language: c
:emphasize-lines: 2,9-11
:linenos:
If the patch is very long you will probably want to add it as a subpage so let's do that now
If the patch is very long you will probably want to add it as a subpage which can be done as follows
.. toctree::
:glob:
......@@ -101,8 +164,12 @@ If the patch is very long you will probably want to add it as a subpage so let's
patch
.. Remember to change the reference "patch" for something unique in your patch file subpage or you will have
cross-referencing problems
you can reference it with :ref:`patch`
.. Here are the URL references used
.. Here are the URL references used (which is alternative method to the one described above)
.. _ReST: http://docutils.sourceforge.net/docs/user/rst/quickref.html
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment