H5MD - proposal 102: Storage of charges
---------------------------------------

**status:** Accepted in H5MD 1.1

### Objective

This proposal aims at defining the storage of the charge associated with each
particle.

### Motivations

Charge data is missing from H5MD 1.0. It is, at the very least, useful for
atomic-level simulations. The interpretation of the value depends however on the
situation.

See the original request and the subsequent discussion
http://thread.gmane.org/gmane.science.simulation.h5md.user/685

This proposal does not list explicitly all use cases but clarifies the most
common interpretations.

### Comparison to other file formats

#### PDB

PDB stores integer atomic charge
<http://www.wwpdb.org/documentation/format33/sect9.html#ATOM>.

### MOSAIC

The [Mosaic format](http://mosaic-data-model.github.io/) relies on so-called
conventions to clarify the interpretation of data elements. See the article on
MOSAIC <http://dx.doi.org/10.1021/ci400599y> and the
[Mosaic PDB convention](http://mosaic-data-model.github.io/mosaic-specification/pdb_convention.html).

### Other file formats

Currently, no other file format clarifies the meaning of the `charge` data element.

### Data in particles group

`charge`
:   An element that contains the charge associated to each particle as a
    scalar, of `Integer` or `Float` type.

    `charge` has the optional attribute `type` of fixed-length string datatype
    and of scalar dataspace, possible values are `effective` and `formal`. In
    the case `effective`, the charge is part of an effective description of the
    interactions with the precise meaning depending on the underlying empirical
    force fields or coarse-grained models.

    In the case `formal`, the charge is the so-called "formal charge" assigned
    to an atom (see <http://en.wikipedia.org/wiki/Formal_charge>) and must be
    of `Integer` type. This case corresponds to the entries in PDB files (see
    definition in the PDBx/mmCIF dictionary
    <http://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v40.dic/Items/_atom_site.pdbx_formal_charge.html>).

	If none of `effective` or `formal` describes the data properly, the
    attribute `type` may be omitted.