Design for AnalysisBase, PlanarBase, CylinderBase, SphereBase
Together with @hejamu here we discuss and propose a design idea for the base classes, relevant for adding the new CylinderBase
, SphereBase
.
Disclaimer: All methods require a working and reliable calculation of the center of mass in periodic cells! I opened an MDAnalysis issue to discuss this. Also a fast wrap and unwrap code is necessary.
AnalysisBase
We distinguish between a moving reference frame with respect to a given atomgroup named refgroup
and a lab frame. Internally, we work only in the lab frame by shifting all coordinates in every frame so that the refgroup
's center of mass is in the center of the box at L/2. After the shift we apply minimum image convention and wrap all coordinates into the primary unit cell. If a module require whole molecules an unwrap operation can be applied afterwards. (Side remark: This requires the fast unwrap code, because already unwrapped trajectories will be wrapped!). With the shifting transformation an analysis module always sees a fixed refgroup at L/2
and does not have to shift any coordinates.
The refgroup parameter will be introduced in AnalysisBase
with a docstring
"""
Parameters
----------
refgroup : MDAnalysis.AtomGroup, default: None
Perform the calculation relative to the center of mass of the
provided AtomGroup. If `None` the calculations are performed relative
to the center of the fluctuating box.
"""
If no refgroup
is provided no shifting and wrapping is performed.
PlanarBase
For the planar class two attributes are important: zmin
and zmax
. The user provides values for these two in the moving reference frame meaning that possible values range from -L/2 to L/2. Internally we convert these into the lab frame by
self.zmin = zmin
self.zmin_lab = zmin - L/2
zmin_lab
has to not be updated in every frame since the com of the refgroup
is always centered at L/2
. The default values of
zmin
and zmax
are supposed to be None
taking the whole box into account. The docstring of the PlanarClass
is supposed to be like
"""
Parameters
----------
dim : int, default: 2
Dimension for binning (x=0, y=1, z=2)
zmin : float, default: None
Minimal coordinate for evaluation (Å) with respect to the refgroup. If `None` all coordinates
up to the cell boundary are taken into account.
zmax : float, default: None
Maximal coordinate for evaluation (Å) with respect to the refgroup. If `None` all coordinates
up to the cell boundary are taken into account.
binwidth : float
binwidth
Attributes
----------
results.z : list
bin position ranging from `zmin` to `zmax`.
"""
CylinderBase
CylinderBase
is a class for a radial Analysis in cylindrical coordinates. In principle, one could also provide an class for an axial analysis.
CylinderBase
will provide an attribute for cylindrical coordinates of all universe atoms as well as rmin
and rmax
"""
Parameters
----------
dim : int, default: 2
Dimension for cylinder axes (x=0, y=1, z=2)
rmin : float, default: 0
Minimal r-coordinate relative to the refgroup's center of mass for
evaluation (Å).
rmax : float, default: None
Maximal r-coordinate relative to the refgroups's center of mass for
evaluation (Å). If `None` the box extension is taken.
zmin : float, default: None
Minimal axial coordinate for evaluation (Å) with respect to the refgroup. If `None` all coordinates
up to the cell boundary are taken into account.
zmax : float, default: None
Maximal axial coordinate for evaluation (Å) with respect to the refgroup. If `None` all coordinates
up to the cell boundary are taken into account.
binwidth : float
binwidth
Attributes
----------
pos_cyl : np.ndarray
Positions of all atoms within the provided universe in cylinder coordinates (r, phi, z).
The origin of the r and phi component is given by the `refgroup`' center of mass.
results.r : list
bin position ranging from `rmin` to `rmax`.
"""
SphereBase
CylinderBase
is a class for a radial Analysis in spherical coordinates.
"""
Parameters
----------
dim : int, default: 2
Dimension for cylinder axes (x=0, y=1, z=2)
rmin : float, default: 0
Minimal r-coordinate relative to the refgroup's center of mass for
evaluation (Å).
rmax : float, default: None
Maximal r-coordinate relative to the refgroups's center of mass for
evaluation (Å). If `None` the box extension is taken.
binwidth : float
binwidth
Attributes
----------
pos_sphere : np.ndarray
Positions of all atoms within the provided universe in spherical coordinates (r, phi, theta).
Positions are given with respect to the `refgroup`'s center of mass.
results.r : list
bin position ranging from `rmin` to `rmax`.
"""