# &app; manual

# &app; Manual V&manrevision;

2006-2012
Jean Bréfort

&legal;

GNOME Documentation Project
Jean
Bréfort

     jean.brefort@normalesup.org

&app; Manual V&manrevision;
&date;

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.12.0
April 2010

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.10.0
September 2008

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.8.0
September 2006

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.6.0
November 2003

Jean Bréfort jean.brefort@ac-dijon.fr

GNOME Documentation Project

&app; Manual V0.1
2001

Jean Bréfort jean.brefort@ac-dijon.fr

GNOME Documentation Project

This manual describes version &appversion; of &app;.

## Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, go to the &app; home page.

&app; allows you to edit and display crystalline structures.

## Introduction

The &app; application is a simple crystalline structures visualizer. It uses its own file format, and is also able to open CIF and CML files.

&app; files can also be displayed in a html page if you use a mozilla based navigator.

This document is by no way a crystallography manual and used notions are not systematically described here in.

## Getting started

### To Start &app;

You can start &app; in the following ways:

Applications list

  Choose Gnome Crystal Crystalline Structures Viewer. It might be listed either in the Education or Science category.

Command line

  Type `gcrystal`, then press Return.

### When You Start &app;

When you start &app;, the following window is displayed:

#### &app; document window

Screenshot of the Gnome Crystal document window.

The &app; window contains the following elements:

Menubar

  The menus on the menubar contain all of the commands you need to work with files in &app;.

Main Toolbar

  The toolbar contains a subset of the commands that you can access from the menubar.

Display area

  The display area contains the contents of the file that you are displaying and/or editing.

Statusbar

  The statusbar displays information about current &app; activity and contextual information about the menu items. The default display is the space group number for the current file.

### To Open a File

To open a file, choose File Open to display the Open File dialog. Select the file that you want to open, then click OK. The file is displayed in a new &app; document window.

To Open a recently opened file, choose the appropriate entry in File Open recent

&app; can open files on a distant server. If the file is read-only, the File Save menu item and the corresponding tool button are disabled.

Saving CIF or CML files in not fully implemented, and a lot of fields will be lossed. Only the crystal structure will be saved.

You can open multiple files in &app;. Each file is opened in it's own top-level window.

### To Open Multiple Files from a Command Line

You can run &app; from a command line and open a single file or multiple files. To open multiple files from a command line, type the following command, then press Return:

`gcrystal file1 file2 file2 ...` where file1 and others, might be relative, absolute paths or uris.

When the application starts, a &app; window is created for each file that you specified.

## General operations

### To Create a New File

To create a new file, choose File New . The application displays a new file in the &app; window.

### To Save a File

You can save files in the following ways:

- To save changes to the current file, choose File Save or click Save on the toolbar. If the file does not have a file name, &app; displays the Save As dialog. Enter a name for the file in the Save As dialog, choose a file format, then click OK.

- To save a new file or to save an existing file under a new file name, choose File Save As . Enter a name for the file in the Save As dialog box, choose a file format, then click OK.

&app; file names use the .gcrystal extension. You do not have to type the extension, it will be added automatically.

### To Export the Current View to a Graphic Format

To export the current file to an image, use File Save As Image .

Available formats are VRML, PDF, Postscript, Encapsulated Postscript, and the formats with write support in GdkPixbuf.

To choose a format, you can use an appropriate extension in the file name, or explicitly select a format in the combo box. With the first method, if &app; does not recognize an extension, the exported file will be a VRML file. &app; will add an extension to the file name if needed.

### To Print the Current View

To print the contents of the current view, use File Print .

&app; uses OpenGL to print the image. The color depth will be for this reason the one used by the X server. The resolution used for printing can be changed in the Settings Dialog choose Edit Preferences . The Preferences dialog box opens (see ). Printing can be a lengthy operation even with a 300 dpi resolution; higher resolutions might be unpracticable.

File Preview opens a window with a preview of the printed output.

To tune the printed output, choose File Page setup... as explained below.

#### The page setup dialog.

the first tab of the dialog concerns the paper and margins setup. Headers and footers are not supported in the version of &app;

##### The Page Setup tab.

Screenshot of page setup dialog.

The second tab allows you to choose the scale of the output. With no scaling or scaling at 100%, the output will have the same size in points as the size in pixels on the screen. If you choose automatic scaling, you can make the output fill the available space either horizontally, vertically, or both (none of the options is equivalent to no scaling).

Printing to more than one page is not supported in this version of &app;

##### The Print Scale tab.

Screenshot of the printing scale page.

### To Change &app; Settings

#### Printing resolution

##### Printer Resolution Page

Screenshot of the Printer Resolution Page.

Printing needs that an OpenGL window. The properties page "Printing parameters" allows you choose the printer resolution in the list. If your printer resolution is not in the list, select the "Other" option and give the right value in the appropriate text entry. As the printer resolution is much larger than the screen resolution and the buffer used has the same size as the view, the scene is splitted in as many parts as necessary to build the whole image sent to the printer. Printing can be a lengthy operation even with a 300 dpi resolution; higher resolutions might be unpracticable.

#### Views default parameters

##### View Defaults Page

Screenshot of the Default View Settings Page.

Parameters available in this page are those that will concern every new view when it is created. To change the same parameters for already opened views, you should use the View menu (see )

Available parameters are background color, field of view, and model orientation defined by Euler's angles.

## Defining the crystal.

### Lattice

#### Lattice Dialog

Screenshot of the Lattice Dialog Box.

The unit cell is defined by the length of its three edges `a`, `b` et `c` and by the three angles α, β, et γ between two vertices.

Depending upon the selected Bravais lattice, some of these parameters are fixed or dependents. Only independent parameters may be changed, entries corresponding to constant or dependent values are disabled.

Lengths must be given in picometers and angles are expressed in degrees.

You can choose a symmetry space group using the spin button or check the "Automatic" button to ask to &app; to detect the correct space group for you. Currently &app; does not make any attempt to move the origin to find the best possible space group, so the detected group might not be the expected one.

### Atoms

#### Atoms Dialog

Screenshot of the Atoms Dialog Box.

The screenshot above defines the atoms of a sodium chloride cell.

After adding an atom, it is possible to modify the associated parameters:

x
y
z

  x, y et z are the atom coordinates in the cell given respective to the cell size. For instance, the triplet 0, 0, 0 puts the atom at the cell vertices and if the threee coordinates ere equal to 0.5, the atom will rest at the center of the cell.

Element

  The element is changed by choosing the corresponding button in the periodic table. If no button is checked, the element is unknown.

Charge

  The charge of the atom.

Radius

  The atom is figured as a sphere whose radius is expressed in picometers in the same way as the cell size. While the radius is null, no atom can be added to the model. Gnome Crystal uses a database for radii. In the Radius frame, it is possible to choose the type of the radius (Unknown, Covalent, Ionic, Metallic, or Van der Waals). Only ionic radii can be used when the charge of the atom is not zero. Depending on the choice of element, charge and radius type, a list of corresponding radii from the database is available. If none of these radii is convenient, choose the Custom option and give a value in the entry.

  A scaling factor can be applied to the radius so that the diplayed atom might appear smaller. Acceptable scaling factors are from 1% to 100%.

Color

  The default color for each element is the color used in the periodic table. To change the color displayed or for an unknown element atom, use the custom color chooser.

Changes to the element, the color or the radius are applied to every selected atoms in the list.

The number of visible atoms depends on the model size (see ) and on cleavages (see ).

Buttons at bottom right are used to manage the atoms list:

- Button Add adds an atom to the list with the current parameters if the radius is not null. If there is an inappropriate value, a message appears and the action aborts.

- Button Delete deletes the selected atoms from the list.

- Button Delete all removes every atom from the list.

- Button Select all selects all atoms.

- Button Select element selects all atoms of the current element.

### Lines and Bonds

#### Lines and Bonds Dialog

Screenshot of the Lines and Bonds Dialog Box.

Bonds are not really supported in this version of Gnome Crystal. Lines must be used instead. The difference is that bonds should be defined by the atoms they join when lines are defined by the coordinates or their extremities.

Some special lines can be easily added, checking the corresponding box:

- Cell edges: if the box is checked, a cylinder is added for each cell edge.

- Diagonals: cylinders are added that join opposite vertices in the cell.

- Medians: cylinders are added that join opposite face centers in the cell.

For Other lines defined in the list, a cylinder is added to join the points whose coordinates are given in the appropriate entries. A Cylinder is added for every visible cell if the Single checkbox is not checked.

These lines need coordinates x1, y1, z1 and x2, y2, z2 are the coordinates of the two ends of the line or bond. They must be given in cell coordinates for the two ends in the respective entries.

For very line present in the model, the two following parameters must be defined (for special lines, use the appropriate widgets and for the lines added to the list, use the wigets displayed in the Other lines frame):

Radius

  The radius of the cylinder used to figure the bond or line must be given in pm as is the cell size. If the radius is null, nothing will be added to the model.

Color

  The color of the cylinder used to figure the bond or line is selected by clicking on the button and picking a color in the dialog box that pops.

Changes to the color or the radius are applied to every selected line in the list.

In the screenshot above (got from the diamond sample provided with the sources), cell edges defined with grey color, a 10 pm radius, and some bonds with the same radius, are added and will be repeated in every visible cell.

Bonds and lines effectively visible depend on model size (see ) and cleavages (see ). If one end of the cylinder lies outside of the visible part of the model, the cylinder will be hidden.

Buttons at bottom right are used to manage the bonds and lines list:

- Button Add adds an item to the list with the current parameters if the radius is not null. If there is an inappropriate value, a message appears and the action aborts.

- Button Delete deletes the selected items from the list.

- Button Delete all removes every item from the list.

- Button Select all selects all items.

### Size

#### Size Dialog

Screenshot of the Size Dialog Box.

Model size is expressed as relative cell coordinates. The necessary values are maximums and minimums of the three coordinates

It is also possible to cut the model using cleavages (see ) if one wishes to limit the visible part by planes others than those corresponding to a constant value of a coordinate.

### Cleavages

#### Cleavages Dialog

Screenshot of the Cleavages Dialog Box.

Cleavages are used to hide from the views atoms from planes with a orientation fixed by the Miller indices h, k and l.

If x, y and z are the atomic coordinates relative to the cell, Miller indices define planes as all the points such that hx + ky + lz is a constant. By instance, in a cubic network, (111) planes are perpendicular to the diagonal of the cubic cell going from vertex 0,0,0 to vertex 1,1,1.

Each define cleavage will hide the chosen number of planes beginning from the greatest value for hx + ky + lz that is present in the model. To remove planes from the other side of the model, signs of h, k and l must be reversed.

There is no need to define cleavages of (100), (010) or (001) planes because the same effect may be obtained more easily by changing the size of the model (see below ).

When a cleavage is defined, the model is zoomed so that it fills the view as explained elsewhere (see ). The Fixed model size button allows to keep remaining atoms at the same place in the view which may be useful to chain pictures in a presentation.

Buttons at bottom right are used to manage the cleavages list:

- Button Add adds acleavage to the list with the current parameters.

- Button Delete deletes the selected cleavage from the list.

- Button Delete all removes every cleavage from the list.

## Views operations.

### To Create a New View

To create a new view of the active document, choose Windows Create New Window .

A new view of the active document is created.

The new view is identical to the document active view. This is considered as a modification of the active document.

The new view becomes the active view.

### To Close The Current View

To close the current view, choose Windows Close This Window .

The active view will be closed. If this view is the only one opened for the document and the document has been changed but not saved, a dialog box pops so that you can save the changes, ignore them, or abort the operation. If other views exist, the view is closed without asking anything and the document is marked as dirty.

### To Tune a View

To tune a view, choose Edit Settings . The View Settings Dialog Box opens.

#### View Settings Page

Screenshot of the View Settings Dialog.

This dialog box can be used to change the following parameters:

Background color

  The background color is selected by clicking on the button and picking a color in the dialog box that pops.

Field of view

  The field of view is the angle which sides join the point from which the model is viewed to the nearest sides of the view. So if the view has a larger horizontal size than its vertical size the sides taken into account are the horizontal ones, otherwise, the vertical sides are used. Acceptable values for the field of view are betwwen 0 and 45°. When a 0° field of view is used the projecton is orthogonal. With a 1° field of view, the perspective effect will be hardly perceptible and with a 45° angle, the model will appear sowhat distorted. The default field of view is 10° (unless you changed it) and gives a sensible perspective.

  The distance between the viewpoint and the model is calculated to be the shortest so that the whole model remains visible whatever its orientation is. The only solution to see the model from a longer distance consist, in the present version, in defining a greater model size (see ) and defining cleavages to remove extra atoms (see ) while selecting the option of constant model size.

Spatial model orientation

  The model may be oriented with the mouse, clicking on the left button inside the view, dragging until a convenient orientation is obtained, and releasing the button. It also is possible to use this dialog box to choose an orientation by modifying the three Euler's angles ψ, θ, and φ.

  When the three angles are null, `c` axis is vertical, with positive values up, `b` axis is in the view plane with positive values towards the right, and `a` axis points in the direction of the viewer. To bring the model to the position defined by Euler's angles, the operations are, in order:

  - A rotation by angle φ around the vertical axis oriented upwards. Possible values for φ are in the range - 180° to 180°.

  - A rotation by angle θ around the axis perpendicular to the view and pointing towards the viewer. Possible values for θ are from 0° to 180°.

  - A rotation by angle ψ around the vertical axis oriented upwards. Possible values for ψ are in the range - 180° to 180°.

## Support.

### To Ask a Question

If you choose Help Ask a question, your mail agent should pop up with a new message to the Gnome Chemistry Utils mailing list.

Another way to get some help is to connect on the #gchemutils channel at irc.gimp.net and ask your question there (if you are not alone on the channel).

### To Find the Gnome Chemistry Utils on the Web.

If you choose Help Gnome Chemistry Utils on the web, the default web browser should pop up and display the main page for the Gnome Chemsitry Utils.

The main page is http://gchemutils.nongnu.org and the project page at savannah http://savannah.nongnu.org/projects/gchemutils.

### To Report a Bug

To report a bug, you must use the bug page for the Gnome Chemistry Utils at Savannah. You can access it by choosing Help Report Bugs (hopefully you'll have only one at once to report).

You can also type the bug report page address directly in the browser. The bug repository is at https://savannah.nongnu.org/bugs/?group=gchemutils

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

        Free Software Foundation, Inc.
        51 Franklin St - Fifth Floor
        Boston, MA 02111-1307
        USA