XCrySDen --
(X-Window) CRYstalline Structures and DENsities

[Figure]
Home | About | Description | Documentation | Download | News | Links
HOWTO: customization of XCrySDen

Table of Contents

Description of ~/.xcrysden/custom-definitions file
    Defining the CRYSTAL program
    Definitions related to GAUSSIAN program
    Printing and image manipulations
    Defining MPEG and GIF encoders
    Defining custom atomic radii and colors
    Customizing various display parameters
    Debugging
    Adding a new input filter (i.e. import new file-format) to XCrySDen

Description of ~/.xcrysden/Xcrysden_defaults file

XCrySDen can be customized to some extent. For this reason the ~/.xcrysden directory exists. Therein reside the following two files: custom-definitions and Xcrysden_defaults. The former file is used for setting some definitions, such as the image conversion program (for example the convert program of ImageMagick), which is used for conversion between different graphics formats while printing to a file (this enables to print to various formats such as JPG/PNG/GIF/TIFF). In the second file the X-resources for XCrySDen are specified, such as fonts and colors.

Description of ~/.xcrysden/custom-definitions file

Defining the CRYSTAL program

If the CRYSTAL program is installed on the computer, and one would prefer to enable its use in XCrySDen, then the system(c95_exist) variable should be set to 1, and the location of CRYSTAL modules should be defined. Here is an example:

# ------------------------------------------------------------------------
#  do we have CRYSTAL package
# ------------------------------------------------------------------------

set system(c95_exist) 1


# ------------------------------------------------------------------------
#  CRYSTAL modules
# ------------------------------------------------------------------------

set system(c95_integrals)  /home/tone/bin/crystal
set system(c95_scf)        /home/tone/bin/crystal
set system(c95_properties) /home/tone/bin/properties
                
In case the CRYSTAL program is not present, or its use should be disabled, then the system(c95_exist) variable should be set to 0, and the definition of CRYSTAL modules should be left undefined (or commented with #). For CRYSTAL03, the integrals and scf modules are the same: namely, the module is named as crystal, hence the two variables should be set to the same value.

Definitions related to GAUSSIAN program

XCrySDen is able to visualize molecular structures from GAUSSIAN input files, when and only when molecular coordinates are specified by Z-matrix. For this purpose the BABEL program is required. To enable the use of BABEL in XCrySDen add the following definition:

# ------------------------------------------------------------------------
#  BABEL program
# ------------------------------------------------------------------------

set xcMisc(babel) $env(HOME)/bin/babel
                
The BABEL program requires the BABEL_DIR environmental variable to be defined. If this variable is not defined in your shell profile, then you should add the following definition to ~/.xcrysden/custom-definitions file:

# this is the same as environmental BABEL_DIR. When BABEL_DIR is
# defined this is not needed

set xcMisc(babel_dir) $env(HOME)/lib/babel

Printing and image manipulations

The print command can be defined as:

# ------------------------------------------------------------------------
#  print command
# ------------------------------------------------------------------------

set xcMisc(printCommand) {lpr -h}
To enable the printing to graphics format such as PNG/JPG/GIF/TIFF, the image converting program that will convert the PPM to these formats should be specified. A convenient choice is the convert program of ImageMagick (http://www.imagemagick.org/). Here is an example:

# ------------------------------------------------------------------------
#  An image conversion program: we need PPM to PNG/JPG/GIF/... conversion.
#  The "convert" program of ImageMagick (http://www.imagemagick.org/) is
#  a convinient choice.
#
#  It is possible to specify the command-line options. For example:
#
#  set xcMisc(ImageMagick.convert) "/usr/bin/convert \
#                             -quality 90 -border 3x3 -bordercolor black"
#
# Instead one can also use something like:
#
#  set xcMisc(ImageMagick.convertOptions) "-quality 90 -antialias \
#                             -blur 1x1 -trim -bordercolor white  \
#                             -border 20x20 -bordercolor black -border 3x3"
# ------------------------------------------------------------------------

set xcMisc(ImageMagick.convert) /usr/bin/convert 

Defining MPEG and GIF encoders

XCrySDen can also create an Animated GIF or even the MPEG movies for the animation of chemical structures. In this case the corresponding programs that will create Animated GIF or MPEG should be defined. An example is the whirlgif program for creating the Animated GIF. For creating the MPEG movies XCrySDen requires the mpeg_encode program. Here is the example for corresponding definitions:

# ------------------------------------------------------------------------
#  With "whirlgif" program XCRYSDEN can create an Animated-GIF image
# ------------------------------------------------------------------------

set xcMisc(whirlgif) /usr/bin/whirlgif


# ------------------------------------------------------------------------
#  MPEG_ENCODE for creating the MPEG movies
# ------------------------------------------------------------------------

set xcMisc(mpeg_encode) /usr/bin/mpeg_encode

Defining custom atomic radii and colors

Custom atomic radii and colors can be defined by setting the atmRad and atmCol arrays, respectively. Below is an example (I hope it is self explanatory). Read the comments in the example.

# ------------------------------------------------------------------------
# Custom setting of the atomic radii. The syntax is:
#
# set atmRad(atomic_number) radius
#
# Example:
#
# set atmRad(1) 0.5; # custom radius for Hydrogen
# set atmRad(8) 1.2; # custom radius for Oxygen
# ------------------------------------------------------------------------

set atmRad(1) 0.5



# ------------------------------------------------------------------------
# Custom setting of the atomic colors. The syntax is:
#
# set atmCol(atomic_number) {red gren blue}
#
# The components (red,gren,blue) must be in range [0,1]
#
# Example:
#
# set atmCol(1) {0.5 0.5 0.5}; # custom color for Hydrogen
# set atmRad(8) {0.0 1.0 0.0}; # custom color for Oxygen
# ------------------------------------------------------------------------

set atmCol(1) {0.5 0.5 0.5}

Customizing various display parameters

Not only atomic colors and radii but also other display parameters can be customized. The myParam array serves this purpose (see example below). One can customize the parameters such as ball-factors, specefill scale factors, tessellation factor, background of the main display window, etc. Below the corresponding part of custom-definitions file is shown. If one would like to customize a particular parameter, then uncomment the appropriate line and set the value according to current needs. In below example each individual myParam array element is preceded by a short description (i.e. comment).

# -------------------------------------------------------------------------
# Custom setting for a variety of molecular display parameters, such as
# ball-factors, specefill scale factors, tessellation factors, etc.
#
# Below are the default values. If you would like to change the
# default for a particular parameter, then uncomment the appropriate
# line and set the value according to your needs.
# ------------------------------------------------------------------------

## spacefill scale factor
#set myParam(ATRAD_SCALE)     1.40
#
## tesselation factor
#set myParam(TESSELLATION)    15.0 
#
## RGB color of unibonds (each compoenent must be within [0,1])
#set myParam(UNIBONDCOLOR)    {1.00 1.00 1.00} 
#
## Perspective Fovy, Front and Back parameters. The smaller the Fovy
## the larger the perception of perspective. Front and Back parameters
## determine the front and back clipping planes. The smaller the Back
## parameter the more the structure is clipped from the back side. The
## Front parameter is counter-intuitive, meaning the smaller it is the
## more the structure is clipped from the front side.
#
#set myParam(PERSPECTIVEFOVY)  2.5
#set myParam(PERSPECTIVEFRONT) 0.65
#set myParam(PERSPECTIVEBACK)  3.0
#
## ball-factor
#set myParam(BALLF)           0.29
#
## rod-factor
#set myParam(RODF)            0.6
#
## line-width of wireframe display-mode (in pixels)
#set myParam(WFLINEWIDTH)     1
#
## line-width of pointline display-mode (in pixels)
#set myParam(PLLINEWIDTH)     1
#
## line-width of crystal cell's frames
#set myParam(FRAMELINEWIDTH)  1
#
## Lighting-Off outline width
#set myParam(OUTLINEWIDTH)     1
#
## Lighting-On wire line width
#set myParam(WF3DLINEWIDTH)    1
#
## point-size of pointline display-mode (in pixels)
#set myParam(PLRADIUS)        6
#
## chemical connectivity factor
#set myParam(COV_SCALE)       1.05
#
## RGB color of crystal frame (each compoenent must be within [0,1])
#set myParam(FRAMECOL)        {0.88 1.00 0.67} 
#
## line-width of crystal frame
#set myParam(FRAMELINEWIDTH)  1 
#
## rod-factor of crystal frame
#set myParam(FRAMERODF)       0.1
#
## RGB background of XCRYSDEN display window 
## (each compoenent must be within [0,1])
#set myParam(BACKGROUND)      {0.00 0.00 0.00}
#
## maximum number of cells per direction for CRYSTALs
#set myParam(CRYSTAL_MAXCELL)  10
#
## maximum number of cells per direction for SLABs
#set myParam(SLAB_MAXCELL)     20
#
## maximum number of cells for POLYMERs
#set myParam(POLYMER_MAXCELL)  50
#
## default atomic-label font (in X11 XLFD format)
#set myParam(ATOMIC_LABEL_FONT) \
#            -adobe-helvetica-medium-r-normal--12-120-75-75-p-67-iso8859-1
#
# default atomic-label bright and dark color (in clamped-float RGB format)
#set myParam(ATOMIC_LABEL_BRIGHTCOLOR) {1.0 1.0 1.0}
#set myParam(ATOMIC_LABEL_DARKCOLOR)   {0.0 0.0 0.0}
#
#
## this are the parameters for the \"mpeg_encode\" program:
##--BEGIN::
#set myParam(MPEG_ENCODE_PARAM_FILE) {
#PATTERN          IBBPBBPBBPBBPBBP
#OUTPUT           \$output_file
#BASE_FILE_FORMAT PPM
#INPUT_FORMAT     UCB
#\$input_convert
#GOP_SIZE         16
#SLICES_PER_FRAME 1
#INPUT_DIR        \$input_dir
#INPUT
#\$input_files
#END_INPUT
#PIXEL           FULL
#RANGE           10
#PSEARCH_ALG     LOGARITHMIC
#BSEARCH_ALG     CROSS2
#IQSCALE         8
#PQSCALE         10
#BQSCALE         25
#REFERENCE_FRAME ORIGINAL
#BIT_RATE        1000000
#BUFFER_SIZE     327680
#FRAME_RATE      30
#}
##--END
#
# ------------------------------------------------------------------------

Debugging

To enable the printing of debugging messages to stdout/stderr, define the xcMisc(debug) variable and set it to 1. The debbuging output is very chaotic, therefore this option should not be interesting for the majority of users.


# ------------------------------------------------------------------------
#  enable/disable the printing of debugging to stdout/stderr
# ------------------------------------------------------------------------

set xcMisc(debug) 1

Adding a new input filter (i.e. import new file-format) to XCrySDen

If the visualization of chemical structures from some format that is unknown to XCrySDen is desired, then it is possible to add a new command line option. In this case one should provide a filter program that will convert this format to XSF format. The usage of such program should be myformat2xsf myfile. The program should read the myfile file (myfile being the name of any file in that format) and write the XSF file to standard output. Here is an example (i.e. a template) converting filter program written in FORTRAN77 (the template can be downloaded from here: myformat2xsf.f).

c     ******************************************************
      program MyFormat2XSF

c     Usage: myformat2xcr myformat_file 
c
c     The program reads the myformat file from myformat_file
c     and writes the XSF file to standard output
c     ******************************************************

      implicit none
      integer MAXATOMS
      PARAMETER (MAXATOMS = 1000)
      character*256 my_file
      real*8
     $     primvec(3,3),        ! primitive lattice vectors
     $     convvec(3,3),        ! conventional lattice vectors
     $     coor(3,MAXATOMS)     ! atomic coordinates
      integer
     $     iargc,
     $     nat(MAXATOMS),       ! atomic numbers
     $     iat, i, j, len       ! counters

      if (iargc().ne.1)
     $     stop 'Usage: myformat2xcr myformat_infile'
      
      call getarg(1,my_file)
      len = index(my_file,' ') - 1
      open(unit=1, file=my_file(1:len), status='old')

c     ***
c     *** READ MyFormat file
c     ***
          ... insert code here ...


c     ***
c     *** WRITE XSF file
c     ***

c     ***  lets suppose it is a CRYSTAL structure
c     ***  other posibilites are (SLAB,POLYMER,MOLECULE)

      write(*,*) 'CRYSTAL'
      write(*,*) 'PRIMVEC'
      write(*,1000) primvec
      write(*,*) 'CONVVEC'
      write(*,1000) convvec
      write(*,*) 'PRIMCOORD'
      write(*,*) iat, 1
      do i=1,iat
         write(*,1001) nat(i), (coor(j,i), j=1,3)
      enddo

 1000 format(2(3(F15.9,2X),/),3(F15.9,2X))
 1001 format(I5,3(F15.9,2X))
      END
To add an option for the above example to xcrysden, add the following entry to ~/.xcrysden/custom-definitions file.

#
# ------------------------------------------------------------------------
#  Here go custom user-specified options
# ------------------------------------------------------------------------
#  In order to add an --unknown option (i.e "unknown" stands for new
#  format to add) to the XCRYSDEN allowed options, do the following:
#  
# Usage: 
#       addOption option converterProgram description
#
# Arguments:
#       option           ... option to add to XCRYSDEN options
#
#       converterProgram ... program that converts from an "unknown"
#                            to XSF format; this program must be
#                            supplied by the user !!!
#
#       description      ... description of the options that will
#                            appear in the help message 
#                            (i.e. xcrysden --help).
#
# Example: (suppose the format is "myformat")
#
#       addOption --myformat $env(HOME)/utils/myformat2xsf {
#               load structure from myformat file format
#       }
#
# Example Note: the converting program is myformat2xsf, and
#               /path/to/myformat2xsf is the full pathname for the
#               converting program.

addOption --myformat /path/to/myformat2xsf {
                    load structure from myformat file format
}
Now you can load the myformat files as: xcrysden --myformat file.myformat, where file.myformat is the appropriate filename.

Description of ~/.xcrysden/Xcrysden_defaults file

In this file the X-resources for XCrySDen, such as fonts and colors, are specified. Worth mentioning are two options. The first is the *palette. It will set the palette, that is the master color-scheme for XCrySDen widgets (i.e. buttons, frames, menus, etc.). If you want, for example, XCrySDen to be red, then set *palette: #ff0000. The second option is the *font. If fonts of XCrySDen appear to be too big, then you can set the master font at the end of the file using this option. A simple and useful setting is *font: fixed. Currently, the Xcrysden_defaults file looks as:

# ------------------------------------------------------------------------
# if you have problems with fonts see the end of this file
# ------------------------------------------------------------------------

# ----------------------------
# here you can set palette
# ----------------------------
#*palette: #777


#---------------
# MenuBar 
#---------------

*MenuBar.relief:                    raised
*MenuBar.borderWidth:               2
*MenuBar*activeBackground:          #007d8d
*MenuBar*activeForeground:          #ffffff

*Viewer*activeBackground:           #007d8d
*Viewer*activeForeground:           #ffffff



# ----------------------------
# this is STANDARD !!!
# ----------------------------

*Button.font:     -*-helvetica-medium-r-normal-*-14-*-*-*-*-*-*-
*Menubutton.font: -*-helvetica-bold-r-normal-*-14-*-*-*-*-*-*-

*Entry.background:              #daa
*SilentEntry*Entry.background:  #ddd
*Text.background:               #daa
*Listbox.background:            #daa

*RaisedFrame.relief:            raised
*RaisedFrame.borderWidth:       2
*GrooveFrame.relief:            groove
*GrooveFrame.borderWidth:       2



# ------------------------------------------------------------------------
# stressed color
# ------------------------------------------------------------------------

*ctrl*Button.background:               #b5a266
*ctrl*Button.foreground:               #000000
*ctrl*Button.highlightBackground:      #000
*close*Button.background:              #b5a266
*close*Button.highlightBackground:     #000
*close*Button.foreground:              #000000

*StressText*Message.background:        #b5a266
*StressText*Label.background:          #b5a266
*Fileselect*Message.background:        #b5a266



# ------------------------------------------------------------------------
# datagrid widgets
# ------------------------------------------------------------------------

*DataGridBlock*Frame.background:       #ffce61
*DataGridBlock*Label.background:       #ffce61
*DataGridBlock*Radiobutton.background: #ffce61

*DataGridSubBlock*Frame.background:        #ffff9d
*DataGridSubBlock*Label.background:        #ffff9d
*DataGridSubBlock*Entry.background:        #daa
*DataGridSubBlock*Checkbutton.background:  #99ddaa
*DataGridSubBlock*Checkbutton.selectColor: #000099



# ------------------------------------------------------------
# if you have problems with fonts uncomment the line below
# ------------------------------------------------------------
#*font:fixed


Home | About | Description | Documentation | Download | News | Links
Webmaster: Tone Kokalj
This document was last modified on Wed Oct 7 16:08:45 CEST 2015