User's Guide

marXperts GmbH
Werkstr.3
D-22844 Norderstedt / Germany
Tel. +49 (40) 529 884 0
www.marxperts.com

Installation

1. Supported Operating Systems
2. How to Get It
3. Environment
4. Directory Structure
5. Description of Programs
6. Installation
- 6.1 Download from website
- 6.2 Setup
7. License Key

1. Supported Operating Systems

The executables in the automar distribution have been compiled and are available for the following operating systems:

Name	OS	Version
Linux	CentOS, Ubuntu	≥5.x, ≥ 10.x
Apple	Mac OS X	10.10.x Yosemite

Note: Apple Mac OS X requires X11 (XQuartz) that must be obtained and installed separately. The programs also rely on MacPorts libraries for X11 to be installed in /opt/local.

2. How to Get It

The automar distribution is available free of charge from our website at: http://www.marxperts.com/pub/automar/automar.dist.tgz.

Programs that do not belong to marXperts GmbH, i.e. all CCP4 programs including MOSFLM and AIMLESS must be obtained from the CCP4 web site. Programs denzo, scalepack, XDS and XSCALE are are commercial programs and are therefore NOT included within this distribution.

3. Environment

The environment should best be defined within the shell startup scripts, i.e. files $HOME/.cshrc (C-shell) or $HOME/.tcshrc (TC-shell) or $HOME/.bashrc (Bourne-shell) using the usual nomenclature. When executing the installation script (setup), the additions to the corresponding login scripts will be done automatically. This scipt also takes care about the CCP4-environment settings which are needed for the additional programs from the CCP4-suite.

Name	Description
MARPRCDOCDIR	Location of directory tree with documentation.
MARPRCDATDIR	Directory where to save current session parameters (automar.mix).
MARPRCDEFDIR	Directory where to find default session parameters (automar.defaults) and executable file cleanup.com
AUTOMARDOCDIR	Location of directory tree with documentation. Only used if MARPRCDOCDIR is not defined.
AUTOMARDATDIR	Directory where to save current session parameters (automar.mix). Only used if MARPRCDATDIR is not defined.
AUTOMARDEFDIR	Directory where to find default session parameters (automar.defaults) and executable file cleanup.com Only used if MARPRCDEFDIR is not defined.
AUTOMARDIR	Root directory of the automar distribution with subdirectories `$AUTOMARDIR/man` for the documentation and `$AUTOMARDIR/dat` containing session files. Only used if others are not defined.

4. Directory Structure

The automar program suite directory ($AUTOMARDIR) contains the following directories.

Directory	Contents
`bin/linux`	Binary executables for Linux (RedHat, Ubuntu, etc.)
`bin/osx86`	Binary executables for Mac OS X (Intel)
`ccp4`	Stuff required for defining the environment of CCP4-programs
`man/man`	Unformatted man pages for programs written by marxperts
`man/html`	HTML conversions of unformatted man pages
`man/css`	Style sheets used by HTML pages
`man/layout`	Design elements used by HTML pages
`man/automar`	HTML documentation of automar program suite
`man/automar/img`	Graphics files used by HTML pages
`man/ccp4`	HTML documentation of mosflm and the some CCP4-programs
`dat`	Startup file for program automar (`automar.mix`).
`tmp`	Temporary files used by some CCP4-programs

When installing the automar program suite, make sure to create these directories.

5. Description of Programs

Name	man page	html page	Description
`automar`	yes	yes	GUI for data processing
`marPeaks`	yes	yes	Spot search in images
`marIndex`	yes	yes	Autoindexing
`marPredict`	yes	yes	Predicts patterns from matrix of marIndex
`marStrategy`	yes	yes	Obtains best data collection strategy
`marProcess`	yes	yes	Integrates images
`marPost`	yes	yes	Postrefinement and addition of partials
`marScale`	yes	yes	Scales and merges data from marProcess-run
`sortmtz/binsort`	no	yes	Sorts "mtz"-file from mosflm-run
`aimless`	no	yes	Scales and merges data from mosflm-run
`truncate`	no	yes	Converts intensities to structure factors
`mar2mtz`	no	yes	Converts output from marScale into "mtz"-file
`mtz2various`	no	yes	Converts binary "mtz"-files into other formats
`mtzdump`	no	yes	Lists contents of binary "mtz"-files
`mtzutils`	no	yes	Various data manipulation tools for "mtz"-files

6. Installation

6.1 Download

Download the desired tgz-packages from the ftp site (see above). You should download files:

automar.dist.tgz
Move packages to a new temporary directory, i.e. type:
mkdir $HOME/tmp/new
Go to this directory, i.e. type:
cd $HOME/tmp/new
Untar the gzipped tar file, i.e. type:
tar xvfz automar.dist.tgz
Run the installation script, i.e. type:
automar/automar-install

6.2 Setup

The "automar-install"-installation script is a text based shell script that will ask you a couple of questions. Defaults (in [brackets]) will be applied when just typing return. The default location of the automar program suite should be $HOME/automar.

The "setup"-procedure will modify your login scripts (either .cshrc or .tcshrc) and append the new path names and environment parameters at the end of the file.

After finishing the "setup"-procedure, source the .cshrc or .tcshrc file and start work, e.g. by typing: automar

If for some reasons the automar-install script fails, it is easy enough to do the setup manually. The installation consists of:

Copying the entire automar distribution to a defined place, e.g. to $HOME/automar.
Modify the shell scripts initialization files, i.e. file $HOME/.cshrc if you are using csh or tcsh as login shell or $HOME/.bashrc if you are using basgh as login shell.

In the login shell initialization scripts you will have to set some environment parameters, in particular AUTOMARDIR and AUTOMARDOCDIR, if you like also AUTOMARDATDIR. Then, you have to add the location of the executables to the binary search path.

Example for .cshrc:

	setenv AUTOMARDIR        $HOME/automar
	setenv AUTOMARDOCDIR     $AUTOMARDIR/man
	set path                = ( $path $AUTOMARDIR/bin/linux/i386 )

Example for .bashrc:

	export AUTOMARDIR='${HOME}/automar'
	export AUTOMARDOCDIR='${AUTOMARDIR}/man'
	auto='${AUTOMARDIR}/bin/linux/i386'
	if [ ${PATH} ]; then              
	     export PATH="${PATH}:${auto}"
	else
	     pub=".:/usr/bin:/usr/sbin:/bin:/sbin:/usr/local/bin"
	     export PATH="${pub}:${auto}"
	fi

Some programs out of this software suite make use of a license key mechanism. Please refer to the following section for more details.

7. License Key

IMPORTANT NOTICE

As of version 2.8 of automar published in July 2011 the programs out of automar program suite do NOT require a license file any more. If your programs still ask for a license, please consider to download the latest executables from our website: http://www.marxperts.com/pub/automar/automar.dist.tgz In case you prefer to continue with your existing executables, please read the next paragraph.

The automar software suite is NOT public-domain software. marXperts GmbH, however, does NOT charge license fees for the programs contained within this suite, but users must get registered in order to continue using the programs after a compilation-date coupled period of usage has expired.

License keys will be supplied to customers of marXperts GmbH and Rayonix, LLC, only.

The following programs require a license key:

marPeaks
marIndex
marPredict
marStrategy
marProcess
marPost
marScale
automar

License keys are platform specific. A license key file must be installed on each computer in order to be able to run the programs.

Run program marlicense on each platform where you want to install the corresponding programs. marlicense is contained within the automar software suite. This program requires simple terminal input and produces an ASCII type output file named "marlicense.hostname" that must be mailed to marXperts GmbH.

marxperts will return a crypted license file that must be installed in one of the following locations on the target host computer.

1. /usr/local/mar/marlicense.$HOST
2. $HOME/.marlicense.$HOST
3. ./marlicense.$HOST (i.e. current directroy)

Note, that the returned license file will be void when modified in any single byte. Note also, that $HOST is the computer's hostname as returned by the UNIX command 'uname -n' but without the domain name. Each of the programs tries to read the license files in the given order. This mechanism can be overwritten by defining an environment parameter MARLICENSE, e.g. like this:

setenv MARLICENSE directory/marlicense.XXX

As a last resort, if there is no license key installed at all the programs have a limited lifetime coupled to the date of compilation.