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)