Atom Create

### name

All objects in GAMGI have an alphanumeric name, given by users, to help object identification and selection. This name is shown everywhere an object needs to be identified, including dialogs, statubars and object trees. This name is not used by GAMGI itself for identification purposes or others (although GAMGI cross checks object names and numbers to ensure that they are consistent). The default atom name is the element name.

    Example: <atom ... name="Si"/> (default Si name)
    Allowed values: 20 alphanumeric characters maximum
    (defined in GAMGI_ENGINE_TOKEN) (optional)

### id

Is used to uniquely identify an object when importing a file and is discarded as soon as the operation is completed. Apart from this condition of uniqueness, id is an alphanumeric attribute, exactly as name. There is no default for this parameter. Bonded atoms must have an id, so bonds can point to them.

    Example: <atom ... id="si1"/> (no default)
    Allowed values: 20 alphanumeric characters maximum
    (defined in GAMGI_ENGINE_TOKEN)
    (optional, required if bonded)

### parent

Usually the parent of a given object is identified by file context, as the object that immediately encloses it in the XML hierarchy.

However the parent object can be explicitely indicated using the parent parameter, which points to the id parameter of the parent object. According to GAMGI rules, the parent of a child object must be in the scope defined by the object directly enclosing the child, so this mechanism can be used to downlink an unlimited number of levels but never to uplink (thus preventing impossibly complex files without losing flexibility).

Moreover, this mechanism can never be used to validate an object that has an impossible object enclosing it by pointing it to a correct parent. The XML hierarchical position of an object in a file must always be possible, independently of its parameters.

    Example: <atom ... parent="layer1"/> (no default)
    Allowed values: 20 alphanumeric characters maximum
    (defined in GAMGI_ENGINE_TOKEN) (optional)

### element

Identifies the atom element or a Dummy atom, represented as Du. It must be present, otherwise an error is shown. Accepted values are "Si", " Si", "Si " but not "SI", "si", "S i" or "14".

    Example: <atom ... element="Si"/> (Si element)
    Allowed values: element name (required)

### type

Is useful to describe groups of atoms which share some properties, for example methyl and methilene hydrogens migh have atom types "h3" and "h2", respectively. Although its purpose is different, type is an alphanumeric attribute exactly as name or id. The default is the element name, converted to lowercase.

    Example: <atom type="si" element="Si" ... /> (default Si type)
    Allowed values: 20 alphanumeric characters maximum
    (defined in GAMGI_ENGINE_TOKEN) (optional)

### mass

To set the atom mass. When not indicated, GAMGI uses the default for the atom element. To see the default, just select the Periodic Table from Atom->Create, Atom->Modify or Atom->Config, and then select the element. To change the default select Atom->Config and read Help->Topics->Formats->Config->Atom. By default, GAMGI uses the atomic masses referenced by http://www.webelements.com/.

    Example: <atom mass="15.9994" element="O" ... /> (default O mass)
    Allowed values: positive real, element name (optional)

### radius

To set the atom radius. When not indicated, GAMGI uses the default for the atom element. To see the default, just select the Periodic Table from Atom->Create, Atom->Modify or Atom->Config, and then select the element. To change the default select Atom->Config and read Help->Topics->Formats->Config->Atom. By default, GAMGI uses the covalent radius referenced by http://www.webelements.com/.

    Example: <atom radius="0.7300" element="O"/> (default O radius)
    Allowed values: positive real, element name (optional)

### charge

To set the atom charge. When not indicated remains undefined.

    Example: <atom charge="0.0" element="O"/> (undefined by default)
    Allowed values: real (optional)

### x, y, z

The atom absolute coordinates, a required information.

    Example: <atom ... x="0.0" y="0.0" z="0.0"/> (no default)
    Allowed values: real (required, coupled)

### style

Controls how the atom is shown: a solid sphere or a wired cross. When not indicated, GAMGI uses the default. To change the default select Atom->Config and read Help->Topics->Formats->Config->Atom.

The sphere is designed to give the highest visual quality and is recommended to produce final images of structures, together with lights. A sphere uses considerable screen space though and is time consuming because it is simulated by numerous 2D polygons, so many vertices and normal vectors (to calculate light) must be allocated and calculated all the time. The cross is designed for atomistic modelling work. Both screen space and computing time used are kept to a minimum. Moreover, when atoms are bonded, the crosses are not represented and atoms are identified just by the ends of the lines representing bonds, thus decreasing even further computation needs. However, because lines do not have a 3D representation, diffuse and specular lights are not reflected by these objects, and they become almost invisible when using lights with an ambient component lower than (0.4, 0.4, 0.4).

    Example: <atom style="wired"/> (default)
    Allowed values: wired, solid (optional)

### variancy

The intrinsic size of a solid (spherical) atom in GAMGI is calculated according to the equation:

    intrinsic = size x (variancy x radius + (1 - variancy) x min)

where radius is the element radius currently defined and min is by default the H covalent radius, as defined in GAMGI (0.37). To change the default select Atom->Config and read Help->Topics->Formats->Config->Atom.

In wired mode, variancy is always 0.0 so all atom crosses have a constant size, given by size x min.

In solid mode, variancy controls how the size of the atom spheres is affected by the atom radius. When variancy is 0.0 the atom spheres have all the same size, when variancy is 1.0 the atom spheres are scaled directly by the atom radius.

    Example: <atom variancy="0.0"/> (default)
    Allowed values: 0.0 - 1.0 (optional)

### size

In solid mode, controls the size of the atom spheres. Combining atom size and variancy with bond size, it is possible to obtain a wide range of styles to represent atomic structures.

The default is to represent atoms as constant spheres, slightly larger than the bonds:

    <atom variancy="0.0" size="0.8"/><bond size="0.5"/>

An elegant style is to represent atoms with constant spheres and the same size as bonds:

    Example: <atom variancy="0.0" size="0.5"/><bond size="0.5"/>

To represent compact cristalline structures, atom size and variancy must be 1.0, to be consistent with cell dimensions. This style can also be used to represent molecules, in order to emphasize the atomic radius and electronic distribution:

    <atom variancy="1.0" size="1.0"/>

    Example: <atom size="0.8"/> (default)
    Allowed values: positive real (optional)

To change the default size, select Atom->Config and read Help->Topics->Formats->Config->Atom.

### red, green, blue

Set the atom color. When not indicated, GAMGI uses the default for the atom element. To see the default, just select the Periodic Table from Atom->Create, Atom->Modify or Atom->Config, and then select the element. To change the default select Atom->Config and read Help->Topics->Formats->Config->Atom. GAMGI default colors are essentially a superset of the CPK color scheme introduced by Corey, Pauling and Koltun.

    Example: <atom red="1.0" green="1.0" blue="0.0" element="Si"/>
    (default Si color)
    Allowed values: 0.0 - 1.0, element name
    (optional, coupled)

### scale

Used to scale the atom visual representation, including its child objects. The visual representation of an object is always scaled by its own scale factor multiplied by the scale factor of all parent objects until layer, inclusive.

    Example: <atom ... scale="1.0"/> (default)
    (defined in GAMGI_MESA_SCALE)
    Allowed values: positive real (optional)

Home