2B. Topography

---

--(***) All the commands listed here are not considered if system exportation from a previous simulation is done

---

All the possible features you can find in a mineral surface are named as surface topography. The mineral topography has been demostrated to play an important role in the dissolution rate and mechanims. Therefore, KIMERA gathers a list of commands as complete as possible to create topographical features. Indeed, there are several ways to obtain the same simulation system.

The resulting simulation box of the previous step is modified by removing or adding regions of atoms to create the desired morphology and system shape.

There are two ways of performing the changes:

1- By aiming the geometric position.

For example if we want to remove form our system a cube, we introduce the following command:

REMOVE_CUBE                         (double)x    (double)y    (double)z    (double)side

or if we had it previously removed, we introduce next command to recover it

ADD_CUBE                            (double)x    (double)y    (double)z    (double)side

Additionally, we can set the cube as insoluble

DEFINE_INSOLUBLE_CUBE               (double)x    (double)y    (double)z    (double)side

For the moment, KIMERA has these commands available for cubes, spheres, ellipsoids, and planes:

ADD_SPHERE                          (double)x    (double)y    (double)z    (double)radius 
REMOVE_SPHERE                       (double)x    (double)y    (double)z    (double)radius 
DEFINE_INSOLUBLE_SPHERE             (double)x    (double)y    (double)z    (double)radius 

ADD_ELLIPSOID                       (double)x    (double)y    (double)z    (double)radiusx     (double)radiusy    (double)radiusz
REMOVE_ELLIPSOID                    (double)x    (double)y    (double)z    (double)radiusx     (double)radiusy    (double)radiusz
DEFINE_INSOLUBLE_ELLIPSOID          (double)x    (double)y    (double)z    (double)radiusx     (double)radiusy    (double)radiusz

Note that the ellipsoid and sphere cases can be also described by using the ellipsoid general equation Ax²+By²+Cz²+Dxy+Exz+Fyz+Gx+Hy+Jz+K<1 (Indeed the previous commands does not manage to represent rotated ellipsoids).

ADD_GENERAL_ELLIPSOID               (double)A    (double)B    (double)C    (double)D    (double)E   (double)F   (double)G   (double)H   (double)J   (double)K
REMOVE_GENERAL_ELLIPSOID            (double)A    (double)B    (double)C    (double)D    (double)E   (double)F   (double)G   (double)H   (double)J   (double)K
DEFINE_INSOLUBLE_GENERAL_ELLIPSOID  (double)A    (double)B    (double)C    (double)D    (double)E   (double)F   (double)G   (double)H   (double)J   (double)K

The planes are defined with the general equation of a plane Ax+By+Cz+D=0.

DEFINE_INSOLUBLE_PLANE              (double)A    (double)B    (double)C    (double)D   (double)distance
REMOVE_PLANE                        (double)A    (double)B    (double)C    (double)D   (double)distance
ADD_PLANE                           (double)A    (double)B    (double)C    (double)D   (double)distance

Here the distance parameter set the thickness of the plane (distance is half the tickness).

Tip: Geometric tools like Geodebra3d can be very helpful to create your system.

2- By aiming the system cells. The changes are produced in the cells of the system. These commands only allow changes in specific cells, or planes of cells:

DEFINE_AB_INSOLUBLE_CELLS           (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_b
DEFINE_BC_INSOLUBLE_CELLS           (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_b   (int)length_c
DEFINE_AC_INSOLUBLE_CELLS           (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_c

REMOVE_AB_PLANE_BY_CELLS            (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_b
REMOVE_BC_PLANE_BY_CELLS            (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_b   (int)length_c
REMOVE_AC_PLANE_BY_CELLS            (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_c

ADD_AB_PLANE_BY_CELLS               (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_b
ADD_BC_PLANE_BY_CELLS               (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_b   (int)length_c
ADD_AC_PLANE_BY_CELLS               (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_c

ADD_CELL                            (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c                                      
REMOVE_CELL                         (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c                                      

Note that in all the cases, the pos_cell goes from 0 to DIMENSION_A-1, DIMENSION_B-1 and DIMENSION_C-1 respectively (see previous section).

Dislocations

Special mention is given to this topographical feature because it has been experimentally observed that they play a key role in the dissolution rate and dissolution mechanisms. Dislocations can be screw or edge. Both types of dislocations are usually represented in the bibliography by considering a lineal defect where a line of atoms is removed. This approximation accounts that the energy bond in this spots is so weaken that can be neglectible. A finer approximation can be done in KIMERA, as we will explain in Question and answers section, but this basic approach is also contemplated in KIMERA.

Same as before, we can define a dislocation by aiming the geometric position, or by aiming the system cells:

1- By aiming the geometric position.

It allows a more complete definition since the angle respect to the axes can be defined, and the dislocation radius can be different than a unit cell multiple.

ADD_XY_DISLOCATION                   (double)x    (double)y   (double)radius     
(optional line) FROM_Z_TO_Z          (double)bot_z       (double)top_z 
(optional line) ANGLE_XZ_ANGLE_YZ    (double)angle_xz    (double)angle_yz
                                             
ADD_XZ_DISLOCATION                   (double)x    (double)z   (double)radius     
(optional line) FROM_Y_TO_Y          (double)bot_y       (double)top_y
(optional line) ANGLE_XY_ANGLE_ZY    (double)angle_xz    (double)angle_yz
                                             
ADD_YZ_DISLOCATION                   (double)y    (double)z   (double)radius     
(optional line) FROM_X_TO_X          (double)bot_x       (double)top_x
(optional line) ANGLE_YX_ANGLE_ZX    (double)angle_yx    (double)angle_zx

Two optional lines control the length of the dislocation, where does it start and where does it end, and the angle respect to the axes.

2- By aiming the system cells.

Same commands as before can be used to remove atoms linearly and define a dislocation but the inclination is lo longer available. They can be only defined along a, b and c directions.

REMOVE_AB_PLANE_BY_CELLS            (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_b
REMOVE_BC_PLANE_BY_CELLS            (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_b   (int)length_c
REMOVE_AC_PLANE_BY_CELLS            (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_c

---

Selective topography

All the previous commands can be used selectively by targeting atoms or particles of certain type. They are identical to the previous ones, but they have the TO_TYPE surname and an additional input parameter with the target atom type.

1- By aiming the geometric position.

ADD_XY_DISLOCATION_TO_TYPE                      (text)atom_type  (double)x    (double)y   (double)radius     
                                                   (optional line) FROM_Z_TO_Z          (double)bot_z       (double)top_z
                                                   (optional line) ANGLE_XZ_ANGLE_YZ    (double)angle_xz    (double)angle_yz
                                             
ADD_XZ_DISLOCATION_TO_TYPE                      (text)atom_type  (double)x    (double)z   (double)radius     
                                                         (optional line) FROM_Y_TO_Y          (double)bot_y       (double)top_y
                                                         (optional line) ANGLE_XY_ANGLE_ZY    (double)angle_xz    (double)angle_yz
                                             
ADD_YZ_DISLOCATION_TO_TYPE                      (text)atom_type  (double)y    (double)z   (double)radius     
                                                         (optional line) FROM_X_TO_X          (double)bot_x       (double)top_x
                                                         (optional line) ANGLE_YX_ANGLE_ZX    (double)angle_yx    (double)angle_zx
                                             
ADD_CUBE_TO_TYPE                                (text)atom_type  (double)x    (double)y    (double)z    (double)side       
REMOVE_CUBE_TO_TYPE                             (text)atom_type  (double)x    (double)y    (double)z    (double)side
DEFINE_INSOLUBLE_CUBE_TO_TYPE                   (text)atom_type  (double)x    (double)y    (double)z    (double)side

ADD_SPHERE_TO_TYPE                              (text)atom_type  (double)x    (double)y    (double)z    (double)radius 
REMOVE_SPHERE_TO_TYPE                           (text)atom_type  (double)x    (double)y    (double)z    (double)radius 
DEFINE_INSOLUBLE_SPHERE_TO_TYPE                 (text)atom_type  (double)x    (double)y    (double)z    (double)radius 

ADD_ELLIPSOID_TO_TYPE                           (text)atom_type  (double)x    (double)y    (double)z    (double)radiusx     (double)radiusy    (double)radiusz
REMOVE_ELLIPSOID_TO_TYPE                        (text)atom_type  (double)x    (double)y    (double)z    (double)radiusx     (double)radiusy    (double)radiusz
DEFINE_INSOLUBLE_ELLIPSOID_TO_TYPE              (text)atom_type  (double)x    (double)y    (double)z    (double)radiusx     (double)radiusy    (double)radiusz

ADD_GENERAL_ELLIPSOID_TO_TYPE                   (text)atom_type  (double)A    (double)B    (double)C    (double)D    (double)E   (double)F   (double)G   (double)H   (double)J   (double)K
REMOVE_GENERAL_ELLIPSOID_TO_TYPE                (text)atom_type  (double)A    (double)B    (double)C    (double)D    (double)E   (double)F   (double)G   (double)H   (double)J   (double)K
DEFINE_INSOLUBLE_GENERAL_ELLIPSOID_TO_TYPE      (text)atom_type  (double)A    (double)B    (double)C    (double)D    (double)E   (double)F   (double)G   (double)H   (double)J   (double)K

DEFINE_INSOLUBLE_PLANE_TO_TYPE                  (text)atom_type  (double)A    (double)B    (double)C    (double)D   (double)distance
REMOVE_PLANE_TO_TYPE                            (text)atom_type  (double)A    (double)B    (double)C    (double)D   (double)distance
ADD_PLANE_TO_TYPE                               (text)atom_type  (double)A    (double)B    (double)C    (double)D   (double)distance

2- By aiming the system cells.

DEFINE_AB_INSOLUBLE_CELLS_TO_TYPE               (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_b
DEFINE_BC_INSOLUBLE_CELLS_TO_TYPE               (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_b   (int)length_c
DEFINE_AC_INSOLUBLE_CELLS_TO_TYPE               (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_c
                    
REMOVE_AB_PLANE_BY_CELLS_TO_TYPE                (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_b
REMOVE_BC_PLANE_BY_CELLS_TO_TYPE                (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_b   (int)length_c
REMOVE_AC_PLANE_BY_CELLS_TO_TYPE                (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_c

ADD_AB_PLANE_BY_CELLS_TO_TYPE                   (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_b
ADD_BC_PLANE_BY_CELLS_TO_TYPE                   (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_b   (int)length_c
ADD_AC_PLANE_BY_CELLS_TO_TYPE                   (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c   (int)length_a   (int)length_c

ADD_CELL_TO_TYPE                                (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c
REMOVE_CELL_TO_TYPE                             (text)atom_type  (int)pos_cell_a   (int)pos_cell_b   (int)pos_cell_c

In addtion to change the topography and shape of our system, we can perform changes in the type of the atoms, as we will see in the next section.