Main Page   Compound List   File List   Compound Members   File Members   Related Pages  

csymlib.h File Reference

C-level library for symmetry information. More...

#include "ccp4_spg.h"

Go to the source code of this file.

Functions

CCP4SPG * ccp4spg_load_by_standard_num (const int numspg)
CCP4SPG * ccp4spg_load_by_ccp4_num (const int ccp4numspg)
CCP4SPG * ccp4spg_load_by_spgname (const char *spgname)
CCP4SPG * ccp4spg_load_by_ccp4_spgname (const char *ccp4spgname)
CCP4SPG * ccp4_spgrp_reverse_lookup (const int nsym1, const ccp4_symop *op1)
CCP4SPG * ccp4spg_load_spacegroup (const int numspg, const int ccp4numspg, const char *spgname, const char *ccp4spgname, const int nsym1, const ccp4_symop *op1)
void ccp4spg_mem_tidy (void)
int symfr_driver (const char *line, float rot[][4][4])
void ccp4spg_free (CCP4SPG **sp)
void ccp4spg_register_by_ccp4_num (int numspg)
void ccp4spg_register_by_symops (int nops, float rsm[][4][4])
int ccp4_spg_get_centering (const char *symbol_Hall, float cent_ops[4][3])
int ccp4spg_load_laue (CCP4SPG *spacegroup, const int nlaue)
int ASU_1b (const int h, const int k, const int l)
int ASU_2_m (const int h, const int k, const int l)
int ASU_mmm (const int h, const int k, const int l)
int ASU_4_m (const int h, const int k, const int l)
int ASU_4_mmm (const int h, const int k, const int l)
int ASU_3b (const int h, const int k, const int l)
int ASU_3bm (const int h, const int k, const int l)
int ASU_3bmx (const int h, const int k, const int l)
int ASU_6_m (const int h, const int k, const int l)
int ASU_6_mmm (const int h, const int k, const int l)
int ASU_m3b (const int h, const int k, const int l)
int ASU_m3bm (const int h, const int k, const int l)
char * ccp4spg_symbol_Hall (CCP4SPG *sp)
ccp4_symop ccp4_symop_invert (const ccp4_symop op1)
int ccp4spg_name_equal (const char *spgname1, const char *spgname2)
int ccp4spg_name_equal_to_lib (const char *spgname_lib, const char *spgname_match)
char * ccp4spg_to_shortname (char *shortname, const char *longname)
void ccp4spg_name_de_colon (char *name)
int ccp4spg_pgname_equal (const char *pgname1, const char *pgname2)
ccp4_symop * ccp4spg_norm_trans (ccp4_symop *op)
int ccp4_spgrp_equal (int nsym1, const ccp4_symop *op1, int nsym2, const ccp4_symop *op2)
int ccp4_spgrp_equal_order (int nsym1, const ccp4_symop *op1, int nsym2, const ccp4_symop *op2)
int ccp4_symop_code (ccp4_symop op)
int ccp4_int_compare (const void *p1, const void *p2)
int ccp4spg_is_in_pm_asu (const CCP4SPG *sp, const int h, const int k, const int l)
int ccp4spg_is_in_asu (const CCP4SPG *sp, const int h, const int k, const int l)
int ccp4spg_put_in_asu (const CCP4SPG *sp, const int hin, const int kin, const int lin, int *hout, int *kout, int *lout)
void ccp4spg_generate_indices (const CCP4SPG *sp, const int isym, const int hin, const int kin, const int lin, int *hout, int *kout, int *lout)
float ccp4spg_phase_shift (const int hin, const int kin, const int lin, const float phasin, const float trans[3], const int isign)
int ccp4spg_do_chb (const float chb[3][3])
void ccp4spg_set_centric_zones (CCP4SPG *sp)
int ccp4spg_is_centric (const CCP4SPG *sp, const int h, const int k, const int l)
int ccp4spg_check_centric_zone (const int nzone, const int h, const int k, const int l)
float ccp4spg_centric_phase (const CCP4SPG *sp, const int h, const int k, const int l)
void ccp4spg_print_centric_zones (const CCP4SPG *sp)
char * ccp4spg_describe_centric_zone (const int nzone, char *centric_zone)
void ccp4spg_set_epsilon_zones (CCP4SPG *sp)
int ccp4spg_get_multiplicity (const CCP4SPG *sp, const int h, const int k, const int l)
int ccp4spg_check_epsilon_zone (const int nzone, const int h, const int k, const int l)
void ccp4spg_print_epsilon_zones (const CCP4SPG *sp)
char * ccp4spg_describe_epsilon_zone (const int nzone, char *epsilon_zone)
int ccp4spg_is_sysabs (const CCP4SPG *sp, const int h, const int k, const int l)
int ccp4spg_generate_origins (const char *namspg, const int nsym, const float rsym[][4][4], float origins[][3], int *polarx, int *polary, int *polarz, const int iprint)
void ccp4spg_print_recip_spgrp (const CCP4SPG *sp)
void ccp4spg_print_recip_ops (const CCP4SPG *sp)
int range_to_limits (const char *range, float limits[2])
void set_fft_grid (CCP4SPG *sp, const int nxmin, const int nymin, const int nzmin, const float sample, int *nx, int *ny, int *nz)
int all_factors_le_19 (const int n)
int get_grid_sample (const int minsmp, const int nmul, const float sample)
int ccp4spg_check_symm_cell (int nsym, float rsym[][4][4], float cell[6])


Detailed Description

C-level library for symmetry information.

Functions defining the C-level API for accessing spacegroup properties. The primary spacegroup information comes from the data file syminfo.lib

Author:
Martyn Winn

Function Documentation

int all_factors_le_19 const int    n
 

Checks whether all factors of a number n are less than or equal to 19.

Parameters:
n  Number to be tested.
Returns:
1 on success, O on failure.

int ASU_1b const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 1bar.

Returns:
1 if in asu else 0

int ASU_2_m const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 2/m.

Returns:
1 if in asu else 0

int ASU_3b const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 3bar.

Returns:
1 if in asu else 0

int ASU_3bm const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 3bar1m.

Returns:
1 if in asu else 0

int ASU_3bmx const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 3barm.

Returns:
1 if in asu else 0

int ASU_4_m const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 4/m.

Returns:
1 if in asu else 0

int ASU_4_mmm const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 4/mmm.

Returns:
1 if in asu else 0

int ASU_6_m const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 6/m.

Returns:
1 if in asu else 0

int ASU_6_mmm const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group 6/mmm.

Returns:
1 if in asu else 0

int ASU_m3b const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group m3bar.

Returns:
1 if in asu else 0

int ASU_m3bm const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group m3barm.

Returns:
1 if in asu else 0

int ASU_mmm const int    h,
const int    k,
const int    l
 

Test if reflection is in asu of Laue group mmm.

Returns:
1 if in asu else 0

int ccp4_int_compare const void *    p1,
const void *    p2
 

Comparison of symmetry operators encoded as integers. In ccp4_spgrp_equal, this is passed to the stdlib qsort.

Parameters:
p1  pointer to first integer
p1  pointer to second integer
Returns:
difference between integers

int ccp4_spg_get_centering const char *    symbol_Hall,
float    cent_ops[4][3]
 

Derive centering operators from Hall symbol (deprecated). Centering operators are now read from syminfo.lib

Parameters:
symbol_Hall  Hall symbol for spacegroup
cent_ops  centering operators
Returns:
number of centering operators (0 if none found)

int ccp4_spgrp_equal int    nsym1,
const ccp4_symop *    op1,
int    nsym2,
const ccp4_symop *    op2
 

Sort and compare two symmetry operator lists. Kevin's code. The lists are coded as ints, which are then sorted and compared. Note that no changes are made to the input operators, so that operators differing by an integral number of unit cell translations are considered unequal. If this is not what you want, normalise the operators with ccp4spg_norm_trans first.

Parameters:
nsym1  number of symmetry operators in first list
op1  first list of symmetry operators
nsym2  number of symmetry operators in second list
op2  second list of symmetry operators
Returns:
1 if they are equal else 0.

int ccp4_spgrp_equal_order int    nsym1,
const ccp4_symop *    op1,
int    nsym2,
const ccp4_symop *    op2
 

Compare two symmetry operator lists. Kevin's code. The lists are coded as ints, which are compared. Unlike ccp4_spgrp_equal, the lists are not sorted, so the same operators in a different order will be considered unequal.

Parameters:
nsym1  number of symmetry operators in first list
op1  first list of symmetry operators
nsym2  number of symmetry operators in second list
op2  second list of symmetry operators
Returns:
1 if they are equal else 0.

CCP4SPG* ccp4_spgrp_reverse_lookup const int    nsym1,
const ccp4_symop *    op1
 

Look up spacegroup by symmetry operators and load properties. Allocates memory for the spacegroup structure. This can be freed later by ccp4spg_free().

Parameters:
nsym1  number of operators (including non-primitive)
op1  pointer to array of operators
Returns:
pointer to spacegroup

int ccp4_symop_code ccp4_symop    op
 

Make an integer coding of a symmetry operator. The coding takes 30 bits: 18 for the rotation and 12 for the translation.

Parameters:
op  symmetry operator
Returns:
int code.

ccp4_symop ccp4_symop_invert const ccp4_symop    op1
 

inverts a symmetry operator. The input operator is converted to a 4 x 4 matrix, inverted, and converted back.

Parameters:
ccp4_symop  input symmetry operator
Returns:
inverted symmetry operator

float ccp4spg_centric_phase const CCP4SPG *    sp,
const int    h,
const int    k,
const int    l
 

Return phase of a centric reflection in the range 0.0 <= phase < 180.0. You should first check that reflection really is centric.

Parameters:
sp  pointer to spacegroup
h  reflection index
k  reflection index
l  reflection index
Returns:
phase of a centric reflection

int ccp4spg_check_centric_zone const int    nzone,
const int    h,
const int    k,
const int    l
 

Check indices against a centric zone for a given spacegroup.

Parameters:
nzone  index of centric zone
h  reflection index
k  reflection index
l  reflection index
Returns:
0 if in zone "nzone", non-zero otherwise

int ccp4spg_check_epsilon_zone const int    nzone,
const int    h,
const int    k,
const int    l
 

Check indices against an epsilon zone for a given spacegroup.

Parameters:
nzone  index of epsilon zone (runs from 1 to 13)
h  reflection index
k  reflection index
l  reflection index
Returns:
0 if in zone "nzone", non-zero otherwise

int ccp4spg_check_symm_cell int    nsym,
float    rsym[][4][4],
float    cell[6]
 

Check for consistency between cell dimensions and spacegroup. Latter is identified from symmetry operators.

Parameters:
nsym  No. of symmetry operators.
rsym  Symmetry operators.
cell  Cell dimensions.
Returns:
1 if they are consistent, 0 if there is a problem.

char* ccp4spg_describe_centric_zone const int    nzone,
char *    centric_zone
 

Obtain string description of centric zone.

Parameters:
nzone  index of centric zone
centric_zone  string description of centric zone
Returns:
string description of centric zone

char* ccp4spg_describe_epsilon_zone const int    nzone,
char *    epsilon_zone
 

Obtain string description of epsilon zone.

Parameters:
nzone  index of epsilon zone
epsilon_zone  string description of epsilon zone
Returns:
string description of epsilon zone

int ccp4spg_do_chb const float    chb[3][3]
 

Check whether change of basis is necessary, i.e. whether the change of basis matrix is not the identity.

Parameters:
chb  change of basis matrix
Returns:
1 if change of basis is necessary, 0 otherwise

void ccp4spg_free CCP4SPG **    sp
 

Free memory associated with spacegroup.

Parameters:
sp  pointer to spacegroup

void ccp4spg_generate_indices const CCP4SPG *    sp,
const int    isym,
const int    hin,
const int    kin,
const int    lin,
int *    hout,
int *    kout,
int *    lout
 

Transform reflection (hin,kin,lin) according to spacegroup "sp" and operation "isym". Resultant indices are placed in (hout,kout,lout).

Parameters:
sp  pointer to spacegroup
isym  required operation, see ccp4spg_put_in_asu
hin  input reflection index
kin  input reflection index
lin  input reflection index
hout  output reflection index
kout  output reflection index
lout  output reflection index
Returns:
void

int ccp4spg_generate_origins const char *    namspg,
const int    nsym,
const float    rsym[][4][4],
float    origins[][3],
int *    polarx,
int *    polary,
int *    polarz,
const int    iprint
 

Translated from Alexei Vagin's CALC_ORIG_PS.

Parameters:
namspg  Spacegroup name for printing only.
nsym  Input number of symmetry operators.
rsym  Input symmetry operators.
origins  Array containing alternative origins on output.
polarx  Return whether polar along x axis.
polary  Return whether polar along y axis.
polarz  Return whether polar along z axis.
iprint  If true, print out list of alternative origins.
Returns:
Number of alternate origins for spacegroup.

int ccp4spg_get_multiplicity const CCP4SPG *    sp,
const int    h,
const int    k,
const int    l
 

Return reflection multiplicity factor for a given hkl in a given spacegroup.

Parameters:
sp  pointer to spacegroup
h  reflection index
k  reflection index
l  reflection index
Returns:
reflection multiplicity factor

int ccp4spg_is_centric const CCP4SPG *    sp,
const int    h,
const int    k,
const int    l
 

Function to determine whether or not h,k,l is a centric reflection in spacegroup "sp".

Parameters:
sp  pointer to spacegroup
h  input reflection index
k  input reflection index
l  input reflection index
Returns:
1 if h,k,l is centric, 0 if not centric, and -1 if there is an error.

int ccp4spg_is_in_asu const CCP4SPG *    sp,
const int    h,
const int    k,
const int    l
 

Test whether reflection is in asu.

Parameters:
sp  pointer to spacegroup
h  reflection index
k  reflection index
l  reflection index
Returns:
1 if in asu, 0 otherwise

int ccp4spg_is_in_pm_asu const CCP4SPG *    sp,
const int    h,
const int    k,
const int    l
 

Test whether reflection or it's Friedel mate is in asu.

Parameters:
sp  pointer to spacegroup
h  reflection index
k  reflection index
l  reflection index
Returns:
1 if in asu, -1 if -h -k -l is in asu, 0 otherwise

int ccp4spg_is_sysabs const CCP4SPG *    sp,
const int    h,
const int    k,
const int    l
 

Check if reflection is a systematic absence.

Parameters:
sp  pointer to spacegroup
h  reflection index
k  reflection index
l  reflection index
Returns:
1 if reflection is a systematic absence, 0 otherwise.

CCP4SPG* ccp4spg_load_by_ccp4_num const int    ccp4numspg
 

Look up spacegroup by CCP4 number, and load properties. Allocates memory for the spacegroup structure. This can be freed later by ccp4spg_free().

Parameters:
ccp4numspg  CCP4 spacegroup number
Returns:
pointer to spacegroup

CCP4SPG* ccp4spg_load_by_ccp4_spgname const char *    ccp4spgname
 

Look up spacegroup by name. This is for use by CCP4 programs and is more complicated than ccp4spg_load_by_spgname. For each spacegroup in syminfo.lib it checks the CCP4 spacegroup name first, and then the extended Hermann Mauguin symbol. Allocates memory for the spacegroup structure. This can be freed later by ccp4spg_free().

Parameters:
ccp4spgname  Spacegroup name.
Returns:
pointer to spacegroup

CCP4SPG* ccp4spg_load_by_spgname const char *    spgname
 

Look up spacegroup by the extended Hermann Mauguin symbol. Allocates memory for the spacegroup structure. This can be freed later by ccp4spg_free().

Parameters:
spgname  Spacegroup name in form of extended Hermann Mauguin symbol.
Returns:
pointer to spacegroup

CCP4SPG* ccp4spg_load_by_standard_num const int    numspg
 

Look up spacegroup in standard setting by number, and load properties. Allocates memory for the spacegroup structure. This can be freed later by ccp4spg_free().

Parameters:
numspg  spacegroup number
Returns:
pointer to spacegroup

int ccp4spg_load_laue CCP4SPG *    spacegroup,
const int    nlaue
 

Load Laue data into spacegroup structure.

Parameters:
nlaue  CCP4 code for Laue group
spacegroup  Pointer to CCP4 spacegroup structure
Returns:
0 on success, 1 on failure to load Laue data

CCP4SPG* ccp4spg_load_spacegroup const int    numspg,
const int    ccp4numspg,
const char *    spgname,
const char *    ccp4spgname,
const int    nsym1,
const ccp4_symop *    op1
 

Look up spacegroup from SYMOP. This would not normally be called directly, but via one of the wrapping functions. Allocates memory for the spacegroup structure. This can be freed later by ccp4spg_free().

Parameters:
numspg  spacegroup number
ccp4numspg  CCP4 spacegroup number
spgname  Spacegroup name.
ccp4spgname  Spacegroup name.
nsym1  number of operators (including non-primitive)
op1  pointer to array of operators
Returns:
pointer to spacegroup

void ccp4spg_mem_tidy void   
 

Free all memory malloc'd from static pointers. To be called before program exit. The function can be registered with atexit.

void ccp4spg_name_de_colon char *    name
 

Function to deal with colon-specified spacegroup settings. E.g. 'R 3 :H' is converted to 'H 3 '. Note that spaces are returned and should be dealt with by the calling function.

Parameters:
name  Spacegroup name.
Returns:
void

int ccp4spg_name_equal const char *    spgname1,
const char *    spgname2
 

Compare two spacegroup names. Strings are converted to upper case before making the comparison, but otherwise match must be exact.

Parameters:
spgname1  First spacegroup name.
spgname2  Second spacegroup name.
Returns:
1 if they are equal else 0.

int ccp4spg_name_equal_to_lib const char *    spgname_lib,
const char *    spgname_match
 

Try to match a spacegroup name to one from SYMINFO. Blanks are removed when making the comparison. Strings are converted to upper case before making the comparison. If spgname_lib has " 1 " and spgname_match doesn't, then strip out " 1" to do "short" comparison.

Parameters:
spgname1  First spacegroup name, assumed to be a standard one obtained at some point from SYMINFO
spgname2  Second spacegroup name that you are trying to match to a standard SYMINFO one. E.g. it might have been provided by the user.
Returns:
1 if they are equal else 0.

ccp4_symop* ccp4spg_norm_trans ccp4_symop *    op
 

Function to normalise translations of a symmetry operator, i.e. to ensure 0.0 <= op.trn[i] < 1.0.

Parameters:
op  pointer to symmetry operator.
Returns:
Pointer to normalised symmetry operator.

int ccp4spg_pgname_equal const char *    pgname1,
const char *    pgname2
 

Compare two point group names. Blanks are removed when making the comparison. Strings are converted to upper case before making the comparison. Any initial "PG" is ignored.

Parameters:
pgname1  First point group name.
pgname2  Second point group name.
Returns:
1 if they are equal else 0.

float ccp4spg_phase_shift const int    hin,
const int    kin,
const int    lin,
const float    phasin,
const float    trans[3],
const int    isign
 

Shift phase value associated with hin,kin,lin according to translation and optional sign change. Return in range 0,360.

Parameters:
hin  reflection index
kin  reflection index
lin  reflection index
phasin  Input phase.
trans  Requested translation
isign  If -1, change sign of phase
Returns:
shifted phase

void ccp4spg_print_centric_zones const CCP4SPG *    sp
 

Print a summary of the centric zones of a spacegroup.

Parameters:
sp  pointer to spacegroup
Returns:
void

void ccp4spg_print_epsilon_zones const CCP4SPG *    sp
 

Print a summary of the epsilon zones of a spacegroup.

Parameters:
sp  pointer to spacegroup
Returns:
void

void ccp4spg_print_recip_ops const CCP4SPG *    sp
 

Print reciprocal symops.

Parameters:
sp  pointer to spacegroup
Returns:
void

void ccp4spg_print_recip_spgrp const CCP4SPG *    sp
 

Print details on reciprocal spacegroup.

Parameters:
sp  pointer to spacegroup
Returns:
void

int ccp4spg_put_in_asu const CCP4SPG *    sp,
const int    hin,
const int    kin,
const int    lin,
int *    hout,
int *    kout,
int *    lout
 

Place reflection (hin,kin,lin) in the asymmetric unit of spacegroup "sp". Resultant indices are placed in (hout,kout,lout).

Parameters:
sp  pointer to spacegroup
hin  input reflection index
kin  input reflection index
lin  input reflection index
hout  output reflection index
kout  output reflection index
lout  output reflection index
Returns:
"isym" if successful, 0 otherwise. "isym" = 2*isymop - 1 for reflections placed in the positive asu, i.e. I+ of a Friedel pair, and "isym" = 2*isymop for reflections placed in the negative asu, i.e. I- of a Friedel pair. Here "isymop" is the number of the symmetry operator used.

void ccp4spg_register_by_ccp4_num int    numspg
 

Look up spacegroup in standard setting by number and load into static storage of csymlib_f.

Parameters:
numspg  spacegroup number
Returns:
void

void ccp4spg_register_by_symops int    nops,
float    rsm[][4][4]
 

Look up spacegroup by set of symmetry operators and load into static storage of csymlib_f.

Parameters:
nops  number of symops
rsm  symmetry operators
Returns:
void

void ccp4spg_set_centric_zones CCP4SPG *    sp
 

Set up centric zones for a given spacegroup. This is called upon loading a spacegroup.

Parameters:
sp  pointer to spacegroup
Returns:
void

void ccp4spg_set_epsilon_zones CCP4SPG *    sp
 

Set up epsilon zones for a given spacegroup. This is called upon loading a spacegroup.

Parameters:
sp  pointer to spacegroup
Returns:
void

char* ccp4spg_symbol_Hall CCP4SPG *    sp
 

Function to return Hall symbol for spacegroup.

Parameters:
sp  pointer to spacegroup
Returns:
pointer to Hall symbol for spacegroup

char* ccp4spg_to_shortname char *    shortname,
const char *    longname
 

Function to create "short" name of spacegroup. Blanks are removed, as are " 1" elements (except for the special case of "P 1").

Parameters:
shortname  String long enough to hold short name.
longname  Long version of spacegroup name.
Returns:
Pointer to shortname.

int get_grid_sample const int    minsmp,
const int    nmul,
const float    sample
 

Sets a grid sample greater than minsmp, which has no prime factors greater than 19, and contains the factor nmul.

Parameters:
minsmp 
nmul 
sample 
Returns:
Grid sample or -1 on failure.

int range_to_limits const char *    range,
float    limits[2]
 

Convert string of type 0<=y<=1/4 to 0.0-delta, 0.25+delta, where delta is set to 0.00001 Makes many assumptions about string.

Parameters:
range  input string.
limits  output range limits.
Returns:
0 on success

void set_fft_grid CCP4SPG *    sp,
const int    nxmin,
const int    nymin,
const int    nzmin,
const float    sample,
int *    nx,
int *    ny,
int *    nz
 

Sets an FFT grid for a spacegroup.

Parameters:
sp  pointer to spacegroup
nxmin  minimum sampling on x
nymin  minimum sampling on y
nzmin  minimum sampling on z
sample  default fineness of sample
nx  returns sampling intervals along x
ny  returns sampling intervals along y
nz  returns sampling intervals along z
Returns:
void

int symfr_driver const char *    line,
float    rot[][4][4]
 

Generate symop matrices from description strings This would not normally be called directly, but via one of the wrapping functions SYMFR2 and SYMFR3 in the Fortran API.

Parameters:
line  null-terminated string containing symop descriptions
rot  array of 4x4 matrices
Returns:
number of symops read, or -1 on failure