Generated from scripting.tcl with ROBODoc v3.2.4 on Wed May 25 16:04:51 2005
NAME
scripting -- Scripting facility (v0.1) of XCRYSDEN
COPYRIGHT
Anton Kokalj (C) 2003
FUNCTION
Often a mechanism for automating a particular job is desirable. For
example, one might want to produce several plots of molecular
orbitals of a given molecule. It would be desirable that the display
parameters are exactly the same for all plots. By using the
XCRYSDEN's GUI one would need to open each file and repeat all the
operations for each molecular orbital, and this is largely
redundant. Once the display parameters for one plot are determined
one could produce the others using script which automates the task.
This is the purpose of the "Scripting" class of functions, namely,
to provide an XCRYSDEN shell-script mechanism for achieving such
jobs.
AUTHOR
Anton Kokalj
CREATION DATE
Sometime in February 2003
NOTES
At this stage the API of Scripting is not yet completely fixed and
is used for testing the "scripting" possibility, that is, loading
the tasks from a Tcl script.
NAME
scripting::source
USAGE
scripting::source scriptfile
PURPOSE
This proc is used to source the an XCRYSDEN script. The proc is for
internal use only, namely, the XCRYSDEN uses this proc to sources
the scriptFile.
ARGUMENTS
scriptfile -- name of scripting file
RETURN VALUE
Undefined.
NAME
scripting::open
USAGE
scripting::open option file ?option file? ...
PURPOSE
This proc is used in XCRYSDEN scripts to open structure files. The
usage is very similar to that of xcrysden command, that is, instead
of "xcrysden option file" one calls "scripting::open option file".
ARGUMENTS
args -- the command line arguments (those of xcrysden program)
RETURN VALUE
Undefined.
EXAMPLE
scripting::open --xsf file.xsf
NAME
scripting::exec
USAGE
scripting::exec option file ?option file? ...
PURPOSE
This proc is used inside majorScript of scripting::multiScript.
Instead of calling "xcrysden option file" one calls "scripting::exec
option file".
ARGUMENTS
args -- the command line arguments (those of xcrysden program)
RETURN VALUE
Undefined.
EXAMPLE
scripting::exec --xsf file.xsf
NAME
scripting::multiScript
USAGE
scripting::multiScript majorScript minorScript
PURPOSE
This proc is for multiple-task jobs. For example, one might want to
produce several plots of molecular orbitals of a given molecule. It
would be desirable that the display parameters are exactly the same
for all plots. This proc is provided to facilitate such jobs. In
majorScript one specifies how many times to run XCRYSDEN and what
files to load, and in minorScript one specify what to do with this
files. For example the instruction in minorScript would be how to
render molecular orbitals for each provided file in majorScript (see
example).
ARGUMENTS
majorScript -- a major script
minorScript -- a minor script
RETURN VALUE
Undefined.
EXAMPLE
scripting::multiScript {
# ------------------------------------------------------------------------
# This is the MAJOR script
#
# Lets open a structures from several files (one at a time), and
# print them.
# ------------------------------------------------------------------------
foreach file {file1.xsf file2.xsf} {
scripting::exec --xsf $file
file rename -force print.png $file.png
} {
} {
# ------------------------------------------------------------------------
# This is the MINOR script
#
# It renders and print a structure
# ------------------------------------------------------------------------
scripting::lighting On
scripting::displayMode3D BallStick
scripting::zoom +0.5
scripting::rotate x -90
scripting::rotate y -30
scripting::printToFile print.png windowdump
}
NAME
scripting::lighting
USAGE
scripting::lighting On|Off
PURPOSE
This proc toggles the lighing Off/On display mode.
ARGUMENTS
mode -- the lighting mode (must be On or Off)
RETURN VALUE
Undefined.
EXAMPLE
scripting::lighting On
NAME
scripting::display
USAGE
scripting::display on|off coordinate-system|atomic-labels|crystal-cells|
unicolor-bonds|wigner-seitz-cell|molecular-surface
or
scripting::display on|off perspective ?near-factor? ?far-factor?
or
scripting::display as ball|spacefill covalent|vad-der-waals
or
scripting::display as crystal-cells rods|lines
or
scripting::display as cell-mode primitive|convetional
or
scripting::display as cell-unit cell|asymm
PURPOSE
This proc is used to set the display property of various objects,
such as coordinate system, atomic symbols, perspective projection
etc. The "scripting::display on|off" command will display or
not-display a requested object, while "scripting::display as" will
display particular object as requested.
ARGUMENTS
mode -- the mode of command, must be one of on|off|as
what -- what object to display
args -- the rest of arguments (as requested by particular object)
RETURN VALUE
Undefined.
EXAMPLE
scripting::display on coordinate-system
or
scripting::display as cell-mode primitive
NAME
scripting::displayMode3D
USAGE
scripting::lighting sticks|pipe&ball|ballstick|spacefill
PURPOSE
Switch to requested 3D (i.e. Lighting-On) display mode
ARGUMENTS
mode -- one of allowed 3D display modes
RETURN VALUE
Undefined.
EXAMPLE
scripting::displayMode3D ballstick
NAME
scripting::displayMode2D
USAGE
scripting::lighting wireframe|pointline|pipe&ball|ballstick-1|ballstick-2|spacefill
PURPOSE
Switch to requested 2D (i.e. Lighting-Off) display mode
ARGUMENTS
mode -- one of allowed 2D display modes
RETURN VALUE
Undefined.
EXAMPLE
scripting::displayMode2D ballstick
NAME
scripting::mainWindow
USAGE
scripting::mainWindow maximize
or
scripting::mainWindow resize width height
PURPOSE
Resize the XCRYSDEN main window.
ARGUMENTS
action -- mode od resizing (maximize or resize)
args -- width and height for resize mode
RETURN VALUE
Undefined.
EXAMPLE
scripting::mainWindow resize 500 500
NAME
scripting::displayWindow
USAGE
scripting::displayWindow fullscreen
or
scripting::displayWindow resize width height
PURPOSE
Resize the XCRYSDEN display window of XCRYSDEN's main window.
ARGUMENTS
action -- mode od resizing (fullscren or resize)
args -- width and height for resize mode
RETURN VALUE
Undefined.
EXAMPLE
scripting::displayWindow resize 500 500
NAME
scripting::zoom
USAGE
scripting::zoom step ?nsteps?
PURPOSE
This proc zooms the displayed structure. The optional argument
nsteps determines the number of zooming steps. If it is omitted only
one zooming is performed. The unit of step is fractional, unless %
sign is appended to the step number. In this case the step is in
percentage unit.
ARGUMENTS
step -- the zooming step (typical values between 0 and 1)
nstep -- number of zooming step (default=1)
RETURN VALUE
Undefined.
EXAMPLE
scripting::zoom 0.05
scripting::zoom 5%
NAME
scripting::rotate
USAGE
scripting::rotate x|y|z rotationstep ?nsteps?
or
scripting::rotate xy|xz|yz rotstep_dir1 rotstep_dir2 ?nsteps?
PURPOSE
This proc rotates the displayed objects, either around x, y, or z
axes (x|y|z modes), or around x-and-y, x-and-z, y-and-z axes
(xy|xz|yz modes). In the latter case the rotste_dir1 is the rotation
step for the first axis, while rotstep_dir2 is the rotation step for
second axis. The optional argument nsteps determines the number of
rotation steps. If it is omitted only one rotation is performed.
ARGUMENTS
dir -- direction of rotation (must be one one x, y, z, xy, xz, or yz)
args -- the rest of arguments as requested by particular mode
RETURN VALUE
Undefined.
EXAMPLE
scripting::rotate x 5
or
scripting::rotate x 5 10
or
scripting::rotate xy 5 5
or
scripting::rotate xy 5 5 10
NAME
scripting::printToFile
USAGE
scripting::printToFile ?filename? ?windowdump? ?togl?
PURPOSE
This proc prints to a file the content of the display window. If
windowdump is specified, the display window is dumped to a file.In
the windowdump case make sure that no other window obscures the
display window, as it will appear on the dump. If togl option is
omitted the XCRYSDEN main display window is assumed.
ARGUMENTS
filename -- the name of the file to print to (if not specified or
void, the filename will be queried)
windowdump -- if non-void, the a display window dump is performed
togl -- the pathName of the display window
RETURN VALUE
Undefined.
EXAMPLE
scripting::printToFile print.png
NAME
scripting::_printToFile_imageConvert
USAGE
scripting::printToFile infile outfile
PURPOSE
This proc performs the PPM to PNG/GIF/JPEG image conversion. It is used
internally by printToFile proc.
ARGUMENTS
infile -- name of PPM file to convert (input)
outfile -- name of converted file (output)
RETURN VALUE
Undefined.
EXAMPLE
scripting::_printToFile_imageConvert tmp.ppm print.png
NAME
scripting::load_myParam
USAGE
scripting::load_myParam
PURPOSE
This proc loads the myParam values defined in the script.
ARGUMENTS
None.
RETURN VALUE
Undefined.
EXAMPLE
set myParam(TESSELLATION) 50.0
set myParam(ATRAD_SCALE) 1.00
scripting::load_myParam
NAME
scripting::buildCrystal
USAGE
scripting::buildCrystal nx ?ny? ?nz?
PURPOSE
This proc builds (i.e. generate) a crystal, that is, nx-cells in 1st
direction, ny-cells in second direction, and nz-cells in 3rd
direction.
ARGUMENTS
nx -- number of cells in 1st crystallographic direction
ny -- number of cells in 2nd crystallographic direction
nz -- number of cells in 3rd crystallographic direction
RETURN VALUE
Undefined.
EXAMPLE
scripting::buildCrystal 3 3 3
NAME
scripting::chdir -- an enhanced version of cd
USAGE
scripting::chdir newdir
PURPOSE
This proc is an enhancement of standard "cd" routine. It changes the
directory to $newdir and updates system(PWD) variable.
ARGUMENTS
newdir -- new directory to chdir into
RETURN VALUE
The absolute path of $newdir.
EXAMPLE
scripting::chdir ../
![[Figure]](img/xcrysden-picture-small-new.jpg)