FINDSYM, Version 6, January 2018

Harold T. Stokes, Branton J. Campbell, and Dorian M. Hatch
Department of Physics and Astronomy, Brigham Young University, Provo, Utah
e-mail: stokesh@byu.edu

This program may be distributed without restriction, but if it is used in
research that results in publications, the use of this program should be
acknowledged.

This program identifies the space group of a crystal, given the
positions of the atoms in a unit cell.  Beginning with version 4, this
program will also identify the magnetic space group of a crystal,
given the positions and magnetic moments of the atoms in a unit cell.

See findsym_sample*.in and findsym_sample*.log for sample input and
output files to this program.

Beginning with version 6, we have introduced a new format for the input, 
based on key words.  To use the key-word input, you must give the name
of the input file as an argument:

findsym inputfilename

FINDSYM is still capable of reading the old input style.  It detects from
the content of the input file whether or not is based on key words.  However, 
any new capabilities added to FINDSYM will only be available using the key-word
input, so we encourage users to begin using the new key-word input

FINDSYM can receive input from a CIF file using FINDSYM_CIFINPUT which outputs
an input file for FINDSYM.

findsym_cifinput ciffilename > tempfilename; findsym tempfilename

------------------------------------------------------------------------------

Input using key words

FINDSYM must be run using

findsym inputfilename

The first line in the input file must be:
!useKeyWords
This tells the program that the input file is using key words.  

The remaining key words can appear in any order.  We indicate for each key word
listed below whether it is required or optional.

Each keyword is preceded by "!".  The lines following the key word contain any 
associated data.

!title (optional)
title line to appear on the output

!latticeTolerance (optional)
The accuracy to which dimensions of the unit cell are known.  Units should be
angstroms.  The default value is 0.00001 angstroms.

!atomicPositionTolerance (optional)
The accuracy to which the atomic positions are known.  Units should be
angstroms.  The default value is 0.001 angstroms.

!occupationTolerance (optional)
The accuracy to which the atomic occupations are known.  The default value is 
0.001.

!magneticMomentTolerance (optional)
The accuracy to which the atomic magnetic moments are known.  Units should be
bohr magnetons.  The default value is 0.001 bohr magnetons.

Either !latticeParameters or !latticeBasisVectors is a required key word.
Use one of them.  Do not use both of them

!latticeParameters (required, see above note)
The lattice parameters a,b,c,alpha,beta,gamma.  a,b,c are given in angstroms,
and alpha,beta,gamma are given in degrees.

!latticeBasisVectors (required, see above note)
The cartesian coordinates of the three vectors that define the conventional 
unit cell.  Enter each vector on a separate line. The units should be in 
angstroms.

Henceforth, the term "conventional unit cell" will refer to the unit cell
defined by !latticeParameters or !latticeBasisVectors.

Both !unitCellCentering and !unitCellBasisVectors are optional.  Use either one,
but not both.  If neither one is used, no translations will be added to the
atomic positions.

!unitCellCentering (optional)
Enter a single letter for the known centering of the unit cell:
P (primitive or no known centering), I (body-centered), F (face-centered),
A,B,C (base centered), or R (rhombohedral centered with coordinates of centered
points at (2/3,1/3,1/3) and (1/3,2/3,2/3), the convention used in
International Tables of Crystallography).  The centering translations will
be added to the atomic positions listed in this input file.  If the centering
translations are already included in the atomic positions, enter P.  

!unitCellBasisVectors
Enter the basis vectors of the lattice which defines the unit
cell, if different from the conventional unit cell defined by the lattice
parameters or the lattice basis vectors listed above.  This unit cell does not 
need to be primitive.  The vectors should be given in dimensionless units in
terms of the basis vectors of the conventional lattice.  Enter each vector on a
separate line.  These vector components are dimensionless and must be accurate 
to 3 decimal places.  For example, 1/2 would be entered as 0.5, and 1/3 would be
entered as 0.333.  

Henceforth, the term "unit cell" will refer either to the primitive unit cell
based on the centering defined by !unitCellCentering or to the unit cell 
defined by the basis vectors given in !unitCellBasisVectors.

!atomCount (required)
Enter the number of atoms contained in the unit cell.

!atomType (required)
Enter the symbol for the type of each atom in the unit cell.  These symbols may 
simply be integers (1,2,3...) or actual chemical symbols (Na,Cl...).  Type
may refer to chemical identity (Mg,Na,F,etc.)  or net charge
(Fe+2,Fe+3,...)  or any other characteristic which may distinguish two
atoms so that a symmetry operation that takes one atom into the other
would be forbidden.

!atomPosition (required)
Enter the coordinates of each atom in the unit cell.  Give the coordinates in 
dimensionless units in terms of the basis vectors of the conventional lattice. 
Enter the coordinates of each atom on a separate line.

!atomOccupation (optional)
Enter the occupation of each atom in the unit cell.  Enter the occupation of 
each atom on a separate line.  The default values are 1.

!atomMagneticMoment (required if the structure is magnetic)
Enter the coordinates of the magnetic moment of each atom in the unit cell, even
for atoms with zero magnetic moment.  Give the coordinates in bohr magnetons. 
Enter the coordinates of each magnetic moment on a separate line.

Space-group setting desired for the output:

!monoclinicAxes (optional)
Axes of a monoclinic space group.  Enter a(b)c, c(-b)a, ab(c), ba(-c), (a)bc, 
or (-a)cb.  The axis in parentheses is the unique axis.  The default value is
a(b)c.

!monoclinicCell (optional)
Cell choice of a monoclinic space group.  Enter 1, 2, or 3.  The default value
is 1.

!orthorhombicAxes (optional)
Axes of an orthorhombic space group.  Enter abc, ba-c, cab, -cba, bca, or a-cb.
The default value is abc.

!originChoice (optional)
Origin choice for a space group.  Enter 1 or 2.  The default value is 2.

!hexagonalAxes (optional)
Use hexagonal axes for R-centered hexagonal space groups.  This is the default
value.

!rhombohedralAxes (optional)
Use rhombohedral axes for R-centered hexagonal space groups.  The default is to
use hexagonal axes.

------------------------------------------------------------------------------

Input not using key words

FINDSYM can be run in either of two ways:

findsym inputfilename
findsym <inputfilename

The input file should contain the following information:

(1) title line.  This line is copied to the output, but is otherwise
ignored by the program.

(2a) lattice tolerance: the accuracy to which dimensions of the unit cell are 
known.  Units should be angstroms.  If zero is entered, the
default value of 1.0d-6 angstroms will be used.

(2b) atomic position tolerance: the accuracy to which the atomic positions are 
known.  Units should be angstroms.  If zero is entered, the
default value of 1.0d-6 angstroms will be used.

(2c) magnetic moment tolerance: the accuracy to which the atomic atomic
magnetic momentss are known.  Units should be bohr magnetons.  If zero is 
entered, the default value of 1.0d-6 bohr magnetons will be used.

(3) form of lattice parameters.  Form 1 indicates lattice parameters
will be entered as 3 vectors, and form 2 indicates lattice parameters
will be given in terms of lengths and angles.  This allows two
different ways of entering this data.

(4) lattice parameters.  If form 1 is given, then enter the cartesian
coordinates of the three vectors that define the conventional unit
cell.  Enter each vector on a separate line.  If form 2 is given, then
enter a,b,c,alpha,beta,gamma.  Give the angles, alpha,beta,gamma, in
degrees.

Henceforth, the term "conventional unit cell" will refer to the unit cell
defined by the lattice parameters in (4).

(5) form of basis vectors of unit cell.  Form 1 indicates basis vectors
will be entered as three dimensionless vectors, and form 2 indicates
that a label for the centering will be given.

(6) basis vectors of the unit cell.  

Form 1: Enter the basis vectors of the lattice which defines the unit
cell.  This unit cell does not need to be primitive.  The vectors
should be given in terms of the basis vectors of the conventional
lattice defined in (6).  Enter each vector on a separate line.  These
vector components are dimensionless and must be accurate to 3 decimal
places.  For example, 1/2 would be entered as 0.5, and 1/3 would be
entered as 0.333.  If the unit cell is the same as the conventional
unit cell, enter 1,0,0, 0,1,0, and 0,0,1.

Form 2: Enter the known centering of the unit cell: P (primitive or no
known centering), I (body-centered), F (face-centered), A,B,C (base
centered), or R (rhombohedral centered with coordinates of centered
points at (2/3,1/3,1/3) and (1/3,2/3,2/3), the convention used in
International Tables of Crystallography).

Henceforth, the term "unit cell" will refer either to the primitive unit cell
based on the centering defined in (6) form 2, or to the unit cell 
defined by the basis vectors given in (6) form 1.

(7) number of atoms.  Enter the number of atoms in the unit cell.

(8) types of atoms.  Enter the symbol for each type of atom, one for
each atom in the unit cell.  These symbols may simply
be integers (1,2,3...) or actual chemical symbols (Na,Cl...).  Type
may refer to chemical identity (Mg,Na,F,etc.)  or net charge
(Fe+2,Fe+3,...)  or any other characteristic which may distinguish two
atoms so that a symmetry operation that takes one atom into the other
would be forbidden.

(9) magnetic.  Enter the word, "magnetic," on this line if atoms
in the structure have magnetic moments.

(10) positions of atoms.  Enter the coordinates of each atom in the
unit cell.  Give the coordinates in terms of the basis
vectors of the conventional lattice defined.  These coordinates
are dimensionless.  Enter the coordinates of each atom on a separate
line.

If some atoms have magnetic moments, then enter those on the same line
as the coordinates of their positions.  Enter the magnetic moment for
every atom, even for those with zero magnetic moment.  Give the
components of the magnetic moment along the basis vectors of the
conventional lattice.

(11) settings in the International Tables for Crystallography (optional).
This specifies the setting to be used for the space group in the output.
For each setting desired, enter the command given in the first column
below, each command on a separate line.

     axis b    unique axis b for monoclinic space groups (default)
     axis c    unique axis b for monoclinic space groups
     cell 1    cell choice 1 for centered monoclinic space groups (default)
     cell 2    cell choice 2 for centered monoclinic space groups
     cell 3    cell choice 3 for centered monoclinic space groups
     origin 1  origin choice 1 (when point of inversion is not at origin)
     origin 2  origin choice 2 (point of inversion at origin, default)
     axes h    hexagonal axes for R-centered space groups (default)
     axes r    rhombohedral axes for R-centered space groups

-------------------------------------------------------------------------------

Output

Standard output will repeat the input data and then will give the
following information (a copy of the output will also be written into
the file findsym.log):

Space group identified by

    (a) space group number and symbols from the International Tables
    of Crystallography.  If magnetic, the magnetic space group number
    and symbol will be given in the BNS setting.
    
    (b) origin of the space group with respect to the origin in the
    input data.  Coordinates are dimensionless, given in terms of the
    basis vectors of the conventional unit cell in the input.
    
    (c) basis vectors of the conventional unit cell defined in
    International Tables of Crystallography.  Components are
    dimensionless, given in terms of the basis vectors of the
    conventional unit cell in the input.  
    
    (d) lattice parameters a,b,c,alpha,beta,gamma for the basis
    vectors given in (c).  The lattice parameters have been idealized
    to be consistent with the symmetry of the space group, where
    necessary.
    
    (e) atomic positions in groups belonging to the same Wyckoff
    position.  Coordinates are dimensionless, given in terms of the
    conventional unit cell defined in International Tables of
    Crystallography.  These correspond exactly to the form of the
    Wyckoff positions given in International Tables of
    Crystallography.  The positions have been idealized to be
    consistent with the symmetry of the space group, where necessary.
    If magnetic, the magnetic moment of each atom is also given.

