Provided by: horae_071~svn537+ds1-1_all bug

NAME

       Artemis - interactive EXAFS data analysis

DESCRIPTION

       Artemis is a program for analyzing EXAFS data using theoretical standards from Feff.
       Artemis includes interfaces to Atoms and Feff as well as forms for defining parameters and
       applying those parameters to the paths from the Feff calculation.  Artemis uses chi(k) as
       it's input.  It does not handle any data processing chores, such as converting raw data to
       mu(E) or doing background removal.  Artemis's sister program Athena is the data processing
       program.

SYNOPSIS

       Artemis is a graphical and interactive program written in the perl programming language,
       using the Tk display engine, the Ifeffit EXAFS library, and the PGPLOT plotting library.
       (See below for a list of relevant URLs.)

       Artemis helps you organize all aspects of a fitting project, including running the Feff
       calculation, settings parameters for the Fourier transform and fitting of the data,
       parameterizing the paths from the Feff calculation, running the fit, and plotting the
       results.  The Artemis window is divided into three panels.  The largest panel is the space
       where most of the work happens.  Its content is model and depends on the state of the Data
       and Paths List.  This list is in the center, skinny panel.  The other skinny panel
       contains the controls the are used to specify how plots are made.

       At the top of the window are the menubar and the project bar.  The project bar displays
       the name of the current project file.  It also contains an indicator that tells you if the
       project has been modified since the last time it was saved.  Clicking on the modified
       indicator will save the project (just like C-s or the "Save project" item in the File
       menu).  At the bottom of the screen is the echo area, where Artemis writes all sorts of
       helpful messages as you use the program.

       The Data and Paths list contains a tree-like list of all of the objects that can be
       manipulated as you use Artemis.  When the program starts, two such items are displayed.
       As you run Feff calculations, import Feff paths and other data sets, and run fits, more
       items are added to this list.  In total, there are five kinds of entries in this list,
       each of which controls a diffferent aspect of Artemis.  These five kinds of list entries
       are: (1) fitting parameters, (2) data, (3) fits, (4) Feff calculation, or (5) Feff path.
       When you click on an item in the Data and Paths List, that item will be "selected" and
       "anchored".  A selected item is highlighted in orange.  An anchored item is outlined with
       a dashed line.  Only one item can be anchored.  0, 1, or more items can be selected.

       The anchored item determines the mode of the large panel.  For instance, when the "Guess,
       Def, Set" item is anchored, the main panel will display a page used for setting the
       fitting parameters.  When a data item is anchored, the main panel will display a page for
       setting Fourier tranform parameters, the fitting range, and other parameters associated
       with the data.  Many functions in Artemis depend upon the mode of the main panel.  Some
       features are available only in certain modes.  Each of the modes is described in its own
       document section.  See "SECTIONS OF THE DOCUMENT".

       Plots in Artemis are always made using the selected items.  To plot, for example, data, a
       fit, and several individual paths, it is necessary to select each of those items.  Many
       other functions in Artemis also work on the set of selected items.

       Anchoring and setting paths is usually done by using the mouse in the Data and Paths List,
       although there are several other ways of changing the anchor and selection using the mouse
       or the keyboard.  Here is a list of mouse events useful in the Data and Paths List:

       Left mouse button
           Clicking the left mouse button will clear all selections then select and anchor the
           item clicked.  The main panel will display the page apporpriate to the anchored item.

       Center mouse button
           Clicking the center mouse button will anchor the item clicked without changing the
           selection.  The main panel will display the page apporpriate to the anchored item.

       Right mouse button
           Clicking the right mouse button will anchor the item clicked without changing the
           selection.  It will also post a menu of functions appopriate to the item clicked.
           These menus are the same as the menus in the menubar at the top of the window.  The
           main panel will display the page appopriate to the anchored item.

       Control key + left mouse button
           Clicking the left mouse button while holding down the control key will add the item
           clicked to the group of selected items.  The anchor is not changed.

       Shift key + left mouse button
           Clicking the left mouse button while holding down the shift key will select all items
           between the anchor and the item clicked, inclusively.  The anchor is not changed.

       Left mouse button + mouse drag
           Clicking the left mouse button then dragging the mouse while holding down the button
           will select all items that you drag the cursor over.  The item initially clicked will
           be anchored and the main panel will display the page appopriate to the anchored item.

       Control-k, Control-j
           Hitting the k or j keys while holdong the control key will move the anchor to the
           previous or next item in the list without changing the selection.  The main panel will
           display the page appopriate to the anchored item.  These two key sequences, behave
           differently when the Guess, Def, Set item is anchored.  See The Guess, Def, Set page
           for details

       Control-l
           Hitting the l key while holding down the control key will put focus on the Data and
           Path List.  This allows you to navigate the list using the arrow keys.

       The color and font of the text in the Data and Paths List indicates the status of each
       item.  Any item written in black, upright text is an item that can be plotted.  When a
       data set or Feff path is excluded from the fit, it will be written in brown text.  The
       Guess, Def, Set item and the Feff calculation items are written in italic text.  The
       italic text indicates items that cannot be plotted.  Although these non-plotable items can
       be selected, they will be ignored when a plot is made.

ARTEMIS: The Data Page

       ARTEMIS - The data page

       The data page is displayed in Artemis's main panel when a data item is anchored in the
       Data and Paths List.  See the main document section for an explanation of anchoring and
       selecting items in the Data and Paths List.

       The data page is divided into five sections.  At the top is a box containing the title
       lines associated with these data.  These are read from the input data file, but can be
       edited at any time by the user.  When the data are written to output files, the contents
       of this box are written as headers.  Below the titles box is the name of the data file
       that was imported.  Below that are four boxes containing groups of related controls.

   Data toggles
       This box contains three toggles that control certain aspects of the fit.  The first two
       are only relevant in a multiple data set fit.  When setting up a project containing a
       multiple data set fit, it is sometimes useful to exclude an entire data set from the fit
       without deleting it from the project.  This can be done with the first toggle.  When a
       data set is excluded, it and all items beneath it are shown in brown text in the Data and
       Paths List to indicate that they have been excluded from the fit.

       After the fit is complete, Artemis wants to show off her handiwork and display a plot of
       the data and the just-finished fit.  In the case of a multiple data set fit, you might
       have a preference about which data set gets plotting.  Click this toggle on for your
       prefered data set.

       The third toggle tells Artemis to do a corefinement of the background spline when it
       performs the fit.  This corefinement is, effectively, the same operation that was
       performed by Athena to remove the background from the data.  The "rmin" parameter serves
       the same purpose as Athena's "rbkg" parameter.  When the fit is performed with the
       background corefinement, a spline is used to fit the Fourier components of the data below
       "rmin" and the Feff paths are used to fit the Fourier components between "rmin" and
       "rmax".  The number of parameters used to determine the spline is the number of
       independent points in that portion of the data: "2*delta_k*delta_R/pi", where "delta_k" is
       the range of the Fourier transform and "delta_R" is the range between 0 and "rmin".  The
       advantage of doing the background corefinement, other than the possibility of making the
       fit look nicer at low R, is that correlations between the background parameters and the
       fitting parameters can be measured.

   Fourier transform and fitting parameters
       This box contains the controls used to set the ranges of the forward Fourier transform and
       of the fit.  The fit range is also used as the backward Fourier transform range when a
       plot is q space is made.  See "Pluck buttons" for a discussion of the little quare buttons
       marked with a blue x.

       Other controls are used to set the functional forms of the Fourier transform window used
       in k and R.  The widths of the sills of those functions are set usng the entry boxes
       labeled "dk" and "dr".

   k-weight parameters
       The controls in this box are used to set the values of k-weight to be used in the fits.
       There are togles for turning on k-weight of 1, 2, or 3.  There is also a toggle for
       specifying an arbitrary value of k-weight.

       These are the k-weight values used in the fit but not the k-weight used to plot the data.
       These two purposes of k-weight are handled independently by Artemis.  See Plotting in
       Artemis for a discussion of the plotting k-weight controls.

       People sometimes get confused by the concept of multipl k-weights for fitting.  The
       prupose of choosing a low or high value for k-weight is to attempt to emphasize either the
       low- or high-k end of the data.  Because different regions of the data are sensitive to
       different kinds of parameters, one might choose a low or high value to increase the
       precision of measurement of certain parameters.  Doing multiple k-weight fits is a sort of
       compromise -- a way of emphasizing both ends of the data in the fit.

       The fit is determined by minimizing a quantity called chi-square.  Chi-square is evaluated
       by summing the squares of the difference between the data and the theory.  Since the FT is
       complex, there is a real part and an imaginary part.  So chi-square is proporitional to:

                /                                                    \
           sum <   Re[ data(R) - th(R) ]^2 + Im[ data(R) - th(R)]^2   >
            R   \                                                    /

       In a multiple k-weight fit, there are simply more terms in the sum.  Let's take a kw=1&3
       fit as an example.  This summation is made for the kw=1 data and theory.  And the
       summation is made for the kw=3 data and theory.  The summations are added together and the
       full sum is used to evaluate chi-square.

       At the end of the day, there is only one set of guess parameters that have been optimized
       by the fit.  These guess parameters along with the set parameters are used to evaluate the
       def parameters and the path parameters.  The path parameters are used to evaluate the
       exafs equation for each path.  The exafs equations for the paths are summed up to make the
       best-fit theoretical chi(k).  You have a data chi(k) and a best-fit chi(k).  Those can
       then be plotted however you like -- even using a k-weight that was not used in determining
       the fit.

   Other parameters
       The last box contains several controls that did not fit into theother boxes.  There is a
       menu for selecting the fitting space.  You can choose to fit the data in any of k, R, or q
       space.  The default is to fit in R.

       Epsilon is the uncertainty used to evaluate chi-square.  Normally it is fine to let
       Artemis use the default value (which is determined from the RMS value of the data between
       15 and 25 angstroms in R-space).  In some situations, you may find it useful to explicitly
       set a value for epsilon.

       After the fit, Artemis writes a log file documenting the fit.  Among the information in
       that log file are the correlations between all the fitting parameters.  You can set the
       level below which Artemis will exclude a correlation from this report.

       Finally, there is a menu for selecting the path to use for phase corrected plots.  This
       menu contains the first five paths from each Feff calculation used with the data set.
       When a path is selected for phase corrected plots, the full phase shift of that path --
       both the central atom and scattering atom portions -- will be subtracted from anything
       that is Fourier transformed before it is plotted.  If a path is selected for phase
       correction and you make a plot of, say, the data, the fit, and several paths, the selected
       phase shift will be subtracted from each item before it is plotted.  Phase correction is
       for plotting only.  Fits are always done on non-phase-corrected data.

   Pluck buttons
       Several of the controls on this page a have a small button with a blue x next to them.
       These are called pluck buttons and are used for grabbing values from the plot window.
       When you click on one of these buttons, a prompt will be written to echo area asking you
       to click on a pointin the plot.  When you do so, the value that you clicked on will be
       inserted into the entry box adjacent to the pluck button.  Artemis is careful not to let
       you pluck a k-value from a plot in R, or vice versa.

   Context menus
       As you pass the mouse over labels on the data page, the text under the mouse will change
       color.  This color change is an indication that mouse clicks will do something.  A left
       mouse click on one of these labels will cause a brief description of that parameter to be
       displayed in the echo area.  Many of these descriptions also suggest reasonable values for
       the parameter.

       Clicking the right mouse button on one of the labels will post a context menu of useful
       function.  One such function is restore that parameter to its default value.  If you have
       a muliple data set fit, the other menu options allow you to constrain the parameter
       between data sets.

       The labels at the top of the boxes are all sensitive to the left mouse button.  The labels
       atop the Fourier transform and fit range box and the k-weights box are also sensitive to
       the right mouse click.

ARTEMIS: Guess, Set, Def Parameters

       ARTEMIS - Guess, set, def parameters

       This page is used to define the parameters of the fitting model.  In Artemis there are six
       kinds of parameters:

       Guess
           Guess parameters are the ones that are optimize during the course of the fit to best-
           fit the theory to the data.

       Def Def parameters are typically expressed as math expressions which may be functionally
           dependant upon other parameters.  These math expressions are updated throughout the
           course of the fit.  As the guess parameters are update, so are the def parameters.

       Set Set parameters are evaluated at the beginning of the fit and not updated throughout
           the fit.  This is the main difference between def and set parameters.  Set parameters
           can be numbers or math expressions.

       Restraint
           Restraints are math expressions which, like def parameters, are updated throughout the
           course of the fit, but which take on a special role in the fit.  A restraint is
           evaluated and added in quadrature to the evaluation of the chi-square parameter.  A
           restraint, therefore, can be used to incorporate a a bias in the fitting result
           towards a piece of prior knowledge about the physical system.  See the Ifeffit for a
           complete discussion of restraints.

       Skip
           Skip parameters are maintained in the project but are not used in any capacity in the
           fit.  The point of a skip parameter is to maintain but not use a complicated parameter
           with a complicated math expression.

       After
           An after is similar to a def parameter in that it may be a math expression dependent
           upon other parameters.  An after is not, however, a part of the fitting model.
           Instead it is a parameter that will be evaluated upon completion of the fit using the
           best fit values.  The list of after parameters will be reported in the log file.
           Using an after parameter anywhere in your fitting model will result in Artemis
           reporting an error in the model.  Afters can depend upon other afters, but you should
           take care in with the order that the afters appear in the list.  The after parameters
           will be evaulated only once after the fit, thus circular or out-of-order dependencies
           will not be resolved.

       The Guess, Def, Set page is divided into two sections.  At the top is a listbox containing
       the list of all defined parameters.  At the bottom is the edit area which contains the
       controls used to establish the parameters.

   The parameter listbox
       This area contains a four-column list of all the parameters defined in a project.  The
       left-most column counts the parameters.  The second column contains a tag identifying the
       type of the parameter.  The third column contains the parameter name.  The right-most
       column contains the parameter's math expression.

       Parameters are coded by color and by the tag in the second column.  Guess parameters are
       written in purple text and have the "g:" tag.  Def parameters are written in green text
       and have the "d:" tag.  Set parameters are written in black text and have the "s:" tag.
       Restraints are written in pink text and have the "r:" tag.  Skip parameters are written in
       grey text and have no tag.  After parameters are written in blue-grey text and have the
       "a:" tag.

       There are a large number of mouse clicks and key sequences that serve a purpose in the
       listbox:

       1.  A left mouse click selects a parameter and displays it in the edit area.

       2.  A double click of the left mouse button selects a parameter, displays it in the edit
           area, and prompts you for the parameter annotation.  See "Parameter annotations".

       3.  A right mouse click selects a parameter, displays it in the edit area, and posts a
           contextual menu about that parameter.  The menu has several items in it.  The "Move"
           submenu is sued to reposition the current parameter in the list.  The "Make" submenu
           serves to change the type of the parameter.  The "Copy" item will replicate the
           anchored parameter, appending a few characters to the end of its name.  The "Build
           restraint" item is discussed below.  The "Annotate" menu item prompts for the
           parameter annotation.  The "Find" menu item will search through all parameter and path
           parameter math expressions and show you how that parameter is used in the project.
           The "Grab" menu item is only enabled for guess parameters and will insert the best-fit
           value from a fit as the value for that parameter.  Finally the "Discard" menu item
           will remove that parameter from the list after prompting for confirmation.

       4.  Control-d will define the parameter in the edit area.

       5.  Control-g will grab the current parameters best-fit value from a fit.

       6.  Control-e will show the editing area if it is hidden.

       7.  Control-k and control-j will move the selection up and down in the list.  Note that
           these two key-sequences serve to move the anchor up and down in the Data and Path List
           when the Guess, Def, Set page is not showing.

       8.  Control-n will clear the selection and focus on the parameter name entry box so that
           you can create a new parameter.

       9.  Control-y will prompt you to then hit any of the g, d, s, r, k or e keys to set the
           type of the parameter.  This is only way of setting the parameter type that does not
           involve the mouse.

   Extended selection
       Multiple items in the list of parameters can be selected using the control-click, shift-
       click, and click-drag sequences described for the Data and Paths List and for the log
       viewer.  Only the anchored list item (i.e. the one surreounded by a dashed line and
       displayed in the edit area) can have its name and math expression edited.

       The advantage of extended selection is that certain of the context menu options discussed
       above in item #3 can operate on many parameters at once.  By doing extended selection then
       clicking the right mouse button somewhere in the selected region, the context menu will be
       posted with options for the group of selected parameters.  Currently, groups of parameters
       can have their types set and can be discarded in this manner.

       If you right-click outside the selected region, the extended selection will be cleared and
       the parameter clicked on will be anchored and selected.

   The edit area
       There are three rows of controls in the edit area.  The top row has two entry boxes.  The
       smaller one on the left is for entering the name of the parameter.  The larger one on the
       right is for entering the parameter's math expression.

       Below the entry boxes are a set of five radiobuttons for selecting the type of parameter
       being edited.

       At the bottom of the edit area are five buttons for acting upon the parameter being
       edited.  The "Undo edit" button clears the entry boxes and discards whatever changes were
       just made.  The "New" button is used to define a brand new parameter.  It clears the entry
       boxes, unselects parameters in the listbox, and gives focus to entry box for entering the
       parameter name.  The "Grab" button becomes enabled after a fit is run.  It inserts the
       best-fit value for a guess parameter.  The "Discard" button deletes a parameter from the
       list.  A dialog pops up confirming deletion.  Finally, the "Hide" button removes the edit
       area from view to allow more parameters to be visible in the listbox.  When the edit area
       is hidden, it is replaced by a button for restoring the edit area.

       Here are the details of the behavior of these controls:

       1.  Hitting return in the parameter name entry box defines the parameter, inserts or
           updates it in the listbox, and puts focus on the math expression entry box.  If a math
           expression has not yet been defined, the parameter will be defined as 0.

       2.  Hitting return in the math expression entry box defines the parameter, inserts or
           updates it in the listbox, and leaves focus on the math expression entry box.

       3.  Clicking on any of the radiobuttons defines the the parameter, inserts or updates it
           in the listbox, and leaves the focus unchanged.

   Parameter annotations
       An annotation is a short text string that is associated with the parameter.  This string
       is written to the echo area whenever the parameter is selected in the listbox on the
       Guess, Def, Set page.  The purpose of he annotation is to write a little hint about the
       role played by the parameter in the fiting model.  If a guess parameters has no annotation
       when a fit is run, its annotation will be generated automatically.  The automatic
       annotation for a guess parameter is its best fit value +/- its error bar.  The automatic
       annotation for a def, after, or restrain parameter is its evaluated value after the fit.

   Building restraints
       One of the items in the context menu displayed when right-clicking on a parameter is for
       building restraints based on guess or def parameters.  This tool provides a dialog for
       constructing one particular type of restraint -- the type that coerces a parameter to stay
       within a boundries for its value.  The dialog prompts for a minimum and maximum value and
       for a term called the "amplifier".  The math expression constructed is this one:

           restrain  param_res = penalty(param, min, max) * amp

       The penalty function evaluates to 0 when "param" is between "min" and "max", to
       "abs(min-param)" when "param" is less than "min", and to "abs(param-max)" when "param" is
       greater than "max".  This is added in quadrature to reduced chi-square as the fit is
       evaluated.

       The amplifier term determines the magnitude of the penalty.  A large value for "amp" will
       force the fitted value of "param" not to stray too far outside its bounds.  A small value
       will allow the fit more freedom to let "param" deviate from your initial guess.

       See the Ifeffit FAQ, question 8.1 for more discussion of restraints, including discussion
       of other ways to set restraints that do not involve the "penalty()" function.

       A cautionary note: restraints are not always appropriate.  As an example, if a fit is
       returning a negative value for sigma^2, it may not be appropriate to apply a stiff
       restraint as a way of forcing that sigma^2 to be a value that you expect.  Often, a
       negative sigma^2 is indicative of some other problem in the fitting model such as
       excessive structural disorder, a coordination number that is forced to be too small, the
       incorrect atomic species for a backscatterer, or some such.  Using a restraint on sigma^2
       in a case like this would not fix the problem.  Quite the opposite, it might foster a
       false sense of accomplishment by "fixing" the sigma^2 "problem" without actually
       addressing the actual problem in the fitting model.

   Highlighting
       There is an option in the GDS menu for highlighting parameters.  This prompts you for a
       text string.  Any parameter names or math expressions that match that string will be
       marked with a green background.  This is particularly useful for large parameter lists.
       The text string is interpreted as a perl regular expression and so any valid perl
       metacharacters can be used.  (This includes regular expressions using "(?{ code })" and
       other similar constructions, a practice the author of Artemis does not recommend, but does
       not prevent.)

   Importing and exporting text files
       For large, complex fitting models, it may be convenient to edit the parameter list with a
       text editor or even to write a program which generates the parameters and writes them to a
       text file.  In that case, it is convenient to be able to import and export a textual
       respresentation of the parameter list.  These files are of a simple format.  Any line like
       these:

          guess  a   5
          set    b   6
          def    c   a+b

       can imported to and exported from the Guess, Def, Set page via the GDS menu.  In an
       imported file, any line beginning with any of "guess", "def", "set", "restrain", "after",
       or "skip" will be imported as a parameter.  The second word on the line will be taken as
       the parameter name and the remaining words on the line will be concatinated to form the
       math expression.  On export lines will follow this format:

          type name = math_expression

       Very little error checking is performed upon import to verify that the parameter is
       defined sensibly, so use this feature with caution.

ARTEMIS: ATOMS, The Crystallographic Front End to FEFF

       ARTEMIS - ATOMS, The Crystallographic Front End to FEFF

       The purpose of Atoms is to generate a "feff.inp" file from crystallographic data.  The
       hard part of making a "feff.inp" file is creating the long list of atomic coordinates.
       Atoms thus makes the hard part of running Feff easy, at least for crystalline matrials.

       This page can be used to create input data for Atoms from scratch.  It will also be used
       to display crystallography data imported from an "atoms.inp" file or a CIF file.  To
       import an "atoms.inp" file or CIF file, use the normal file import dialog.

   The title box
       At the top is a text box for entering title lines identifying the crystallographic data.
       These lines will be written to the "feff.inp" file and to the top of the Feff
       interpretation page.  This is a good place to cite the literature reference or to provide
       other important information about the crystal.

   Crystal parameters
       To the left side of the page are entry boxes for entering space group, lattice constants,
       and lattice angles of the crystal.  A space group must always be provided.  Atoms is very
       flexible about how the space group symbol is entered.  You can use the Hermann-Maguin or
       Scheonflies symbols or the index of the space group from the International Tables.  The
       algorithm that interprets the symbol is insensitive to white space and capitalization --
       "P m -3 m" and "PM-3M"  are interpreted the same.  For complete details about how the
       symbols are interpreted, see the Atoms docuemntation on Bruce's web site.

       Lattice constants are entered in units of Angstroms, angles are entered as decimal numbers
       in degrees (and not in arc minutes -- i.e. 89 and a half degrees is entered as 89.5 rather
       than 89'30").  Many space groups have symmetries that make some lattice angles and
       constants the same.  In those situations, it is only necesary to fill in the essential
       values.  For instance, a cubic space group only requires a value for the "a" constant.
       Atoms will know to set the other lattice constants the same and to set the angles to 90
       degrees.  For lower symmetry groups, you must provide all the necessary information.

       Below the lattice constants are entry boxes for "Rmax" and the shift vector and a menu for
       selecting the absorption edge of the Feff calculation.  "Rmax" is the radial extent of the
       cluster that will be written to the "feff.inp" file.  Some space groups are given in the
       International Tables with two different origins -- i.e. the origin is placed at sites with
       two different point symmetries.  The fractional coordinates of the sites are different for
       the two different settings of the crystal.  In those cases, Atoms requires that you use a
       particular one of the two choices.  If your input data has used the other origin choice,
       it should be fairly obvious.  In that case, coordination numbers and distances to the
       coordination shells will usually be obviously wrong.  When you use one of the space groups
       for which two origin choices exist, Artemis will issue a warning.  If you suspect that the
       wrong origin choice has been used, insert the values for the shift vector that were
       reported in the warning message.

       On occassion, crystals are reported in the literature using origins other than the
       standard one used in the International Tables.  A famous example is germanium oxide.  Here
       is the crystal data for GeO2:

          title GeO2 (hexagonal)
          space p 32 2 1
          a=4.98502       c=5.64800
          rmax=6.0        core=Ge
          shift   0 0 0.66667
          atoms
            Ge    0.4513  0.0     0.0
            O     0.3969  0.3021  0.0909

       For some reason, the crystallography reference for this material uses an origin that is
       shifted by 2/3 in the z direction relative to the origin used in the International Tables.
       To get Atoms to compute this structure correctly, the shift vector given above must be
       used.

   The atoms list
       To the right side of the page is the list of unique crystallographic sites.  As new sites
       are created, they are inserted into the list.  The sites are not edited directly, instead
       the editing area at the bottom of the screen is used and the list of all sites is
       displayed here.  This works much the same as the Guess, Def, Set page.

       To edit a site, left-click on its entry in the list.  It's element symbols, coordinates,
       and site tag will be displayed in the edit area.  A right click on a site in the list will
       post a context menu with several functions that can be perfromed on that site.  You can
       re-order the list using the "Move" menu item.  A site can be copied and the copy added to
       the list using the "Copy" menu item.  The "Discard" menu item completely removes the site
       from the list.  The list supports extended selection.  When many sites are selected (i.e.
       highlighted in yellow), the "Discard" menu item will work on all the selected sites.

       Sites can also be reordered using the keyboard.  "Alt-k" and "Alt-j" can be used to move
       the selected site up or down in the list.

   The edit area
       At the bottom of the page is the collection of widgets used to actually create and edit
       unique crystallographic sites.  The element box is used to insert the two-letter element
       symbol for the site.  The site will not be created if this is not a valid symbol.  The tag
       can be any 10-letter string used to identify the site.  The tag is used to differentiate
       sites that contain the same element.

       The boxes for the "x", "y", and "z" coordinates can be filled with floating point numbers
       or simple fractions.  That is, 0.5 and "1/2" are both acceptable.  These coordinates are
       fractional positions in the unit cell and are not Cartesian coordinates.

       Once you have created all sites in your crystal, click the "Run Atoms" button.  This will
       process the crystallographic data, create the "feff.inp" file, display the "feff.inp"
       page.

   Atoms template files
       The "feff.inp" data that is generated when the "Run Atoms" button is pressed is determined
       by the contents of a special template file.  Artemis is distributed with a number of
       template files serving different purposes.  The structure of the "feff.inp" data is set by
       the value of the "atoms->template" preference.  The default value is "feff", which tells
       Artemis to use the template file suitable for running Feff6.

       If you want to run some other version of Feff, you should set the "atoms->template"
       preference variable to the appropriate value.  Templates are provided with Artemis for
       writing Feff7 and Feff8 input files.  Feff8 input files can be written which are suitable
       for XANES or non-self-consistent EXAFS calculations.

       Sometimes, it is useful to modify template files for writing out specialized "feff.inp"
       data.  If these modified template files are placed in "~/.horae/atp/" (unix) or "C:Program
       Files\Ifeffit\horae\atp" (windows), Artemis will be able to find them.

   Final note
       A full explanation of how the Atoms algorithms works is beyond the scope of this document
       page.

ARTEMIS: The FEFF Input File

       ARTEMIS - The FEFF input file

       This page displays the Feff input data, which includes some control parameters and a long
       list of atomic coordinates.  This page is no more sophisticated than a text box which
       serves as a primitive editor and a button at the bottom for running Feff.  Explaining Feff
       is beyond the scope of this document.

       When feff is finished, you will presented with a dialog asking how many paths to import.
       The choices are none, the first path, the first 10 paths, and all paths.  The number in
       the third option is configurable in the preferences dialog.  Should you ever need to rerun
       Feff after starting a project, "none" is usually the right answer.  The other options may
       result in one or more paths being defined twice in the project -- a confusing situation.

       If Feff fails to run to completion, Artemis will try to recognize the problem and post a
       suggestion for how to solve the problem.  If Artemis does not recognize your problem,
       explain it Bruce so he can add that problem to Artemis's database of troubleshooting
       solutions.

ARTEMIS: Interpretation of the FEFF Calculation

       ARTEMIS - Interpretation of the FEFF calculation

       This page provides a concise overview of the Feff calculation.  At the top of the page is
       a summary of some of the statistics of the calculation.  Below that is a chart showing the
       details of each path from the calculation.  For each path, the degeneracy, the half path
       length and the amplitude factor are shown.  The last column shows a tokenized summary of
       the scattering path -- this allows you to see at a glance which atoms were involved in the
       path.

       The information and context menus available on this page allow you organize, understand,
       and manipulate the paths in this Feff calculation.  Pretty much all functions involving
       the paths except writing math expressions for the path parameters are available on this
       page.

   The interpretation chart
       The colors and fonts used in the chart convey information:

       Bold, black font
           These are paths that have been imported into the project and are included in the fit.

       Bold, brown font
           These are paths that have been imported into the project but are excluded in the fit.

       Normal, black text
           These are paths that have not been imported into the project but which are available
           to be imported.

       Normal, grey text
           These are paths that are unavailable for importation into the project.  These can be
           made available by re-running the Feff calculation.  After the Feff run, it is best to
           choose the "import no paths" to avoid reimporting paths already in the project.  After
           that, these paths will be written in normal, black text, indicating that they are
           available for import.

       Light brown background
           The light brown background is used to indicate single scattering paths.

       Light blue background
           The light blue background is used to indicate collinear or nearly collinear multiple
           scattering paths.

   Context menus
       There are interesting and useful context menus on every part of this page.  These menus
       are available by right clicking.

       Right clicking anywhere in the text box at the top of the page will pop up a menu with
       options for viewing files from the Feff calculation.

       Right clicking in the interpretation chart will post a menu of options relevant to the
       path on the line on which you clicked.  Each of the four kinds of paths given by the four
       fonts described above has its own menu.

       For paths that are imported in the fit, the menu offers options for plotting the path,
       displaying that path's page, including or excluding the path in the fit, selecting or
       deselecting that path for plotting, making that path the default for evaluation of def
       parameters after a fit, displaying the text of the file containing the path, or discarding
       the path.  The choices for including or excluding and for selecting or deselecting depend
       on the state of that path in the Data and Paths List. Also some options might be greyed
       out depending on the state of that path.

       For paths that have not been imported into the project, the context menu allows you to
       import the path with the option of displaying its page or leaving the display on the Feff
       interpretation.  For paths that are unavailable for import, a message saying so is posted
       when one of those lines is right-clicked.

       The interpretation chart allows for extended selection of lines in the chart.  You can
       select additional paths by holding the control key while clicking with the left mouse
       button.  Holding the shift key while left clicking selects all line between the anchor
       (the one outlined with a dashed line) and the one you click on.  You can also click and
       drag to select all the lines you drag over.  When more than one line is selected, the
       content of the context menu change to reflect functionality that makes sense for many
       paths.  Extended selection in the interpretation chart is therefore a good way of
       including/excluding, selecting/deselecting, or plotting a large number of paths.

       The context menu that pops up when many lines are selected may be a little surprising.
       Its contents depend upon the state of the anchored line, which in this case is the one
       that you right-click on to post the menu.  The options in the context menu will be
       suitable to the state of the anchored selection regardless of the states of the other
       selected lines.  If you choose a menu item that does not make sense for some of the
       selected lines, those lines will be ignored.

       Here is a concrete example.  Suppose that you select a number of lines, some of which are
       included in the fit and some of which have not been imported in the fit.  If you then
       right click on one of the included paths, you will get options appropriate to included
       paths.  If you then ask to plot the selected paths along with the data, the included paths
       will be plotted and the imported paths will be ignored.  If, instead, you click on one of
       the paths that has not been imported yet, the context menu will give you the option of
       importing the selected paths.  In that case, the paths that have already been imported
       will be ignored.

   Trouble shooting
       On occassion you might see that lines in the Feff interpretation do not properly report on
       the contents of the path.  When this happens, site tags are replaced by this string:
       "<?>".  There are a couple common reasons you might see the "<?>" tags:

       1.  You have done some advanced voodoo with Feff, editing the "files.dat" or "paths.dat"
           files then rerunning the last module to produce specialized output.

       2.  You have discovered a bug in the algorithm Artemis uses to harvest information from
           the Feff calculation.  IN that case, you should send the "feff.inp" file or the
           Artemis project file to Bruce so he can fix the problem.

       Note that the appearance of the "<?>" tags is probably not an indication that Feff has
       misbehaved.  The Feff calculation has to run to completion and generate its normal output
       before this problem can manifest itself.  The Feff calculation is almost certainly usable
       to analyze the data.  The Feff interpretation page is Artemis's attempt to organize
       information about the Feff calculation in some user-friendly format.  That this
       organizational effort failed is not necessarily an indication that Feff failed.

ARTEMIS: The Path Page

       ARTEMIS - The path page

       The path page is displayed whenever a Feff path is selected from the Data and Paths List.
       This page is used to establish the math expressions of the path parameters for this path.

       At the top of the page is a line identifying which Feff calculation this path is from.
       Below that are three toggles.  One is used to include of inlcude or exclude the path from
       use in the fit.  There are many other ways in Artemis to include and exclude paths other
       than to use this toggle.  See The Feff interpretation page and "artemis_menubar" for more
       discussion of this.  Also Control-t is the same as clicking this toggle.

       The second toggle is used to specify paths that you would like plotted after a fit (or sum
       of paths) is finished.  By default, the data and the fit (or sum) is plotted after the fit
       (or sum) and no paths are plotted.  Any paths selected for plotting will be added to the
       plot after the fit (or sum) is finished.

       The third toggle is used to set which path is the default path for evaluation of Def
       parameters after the fit.  It is possible to write math expressions which evaluate
       differently for different paths.  An example might be a math expression using the "reff"
       parameter.  For any such Def parameters, it is necessary to tell Artemis which path should
       be used for the reporting of those parameters in the log file.  The default is to use the
       first path listed in the Data and Paths List.

       Below that is a box which summarizes the path.  This gives some statistics about the path
       as well as displaying a color-coded "map" of the scattering path.  The central atom is
       always displayed in red text.  Other atoms are in black text.  The grey text shows the
       length and scattering angle of each leg of the path.  In the case of a high-order multiple
       scattering path which has legs which have a non-zero Eulerian eta angle between them, the
       eta angle will be displayed as well.  If that last sentence was gibberish, it suffices to
       know that paths of that sort are almost never observable in real EXAFS data.

       At the bottom of the page is the list of path parameters.  This is the most important
       section of the page because it is here that the details of the fitting model are realized.
       There is an entry box for each of the various types of path parameters.  The math
       expression approporiate for each parameter should be entered in the entry box.

       When a Feff calculation is imported into Artemis, a set of automatic parameters are
       generated, entered into the list on the Guess, Def, Set page, and entered into the path
       parameetr boxes for each path imported.  The default behavior of Artemis is to generate a
       set of parameters appropriate for a simple, single scattering, first shell fit.  While it
       might be OK to immediately click the big green button, most fitting models will require
       substantial editing.

       The right mouse button serves many important purposes on the path page.  Clicking the
       right mouse button anywhere in one of the entry boxes will highlight the word underneath
       the cursor and post a menu.  The entries in the menu are for for defining the word as a
       parameter on the Guess, Def, Set page.  For each parameter type there is the option of
       jumping or staying.  In either case, the parameter is defined and added to the list on the
       GDS page.  For jumping, the GDS page is then displayed.  For staying, the current path
       page remains displayed.

       Right clicking on one of the path parameter labels will post a menu of functions related
       to defining path parameter math expressions.  The "Edit" option will pop up a dialog used
       for entering a math expression and then optionally exporting its value to other paths.
       The "Clear" option doies just that.

       The various "Export" options are ways of constraining path parameters to be the same for
       other paths.  The "Grab" options make the current path parameter the same as the path
       parameter in the previous or following path.

       The "sigma^2" label has some additional options.  These insert the syntactically correct
       text appropriate to using either the Correlated Debye or single frequency Einstein models
       for the sigma^2 of the path.

       To enable the display of spaces for the "dphase", "k_array", "amp_array", or "phase_array"
       path parameters, you must click on the "Extended path parameters" button in the Paths
       menu.

ARTEMIS: The Log Viewer

       ARTEMIS - The log viewer

       When a fit is anchored in the Data and Paths list, the log file viewer is displayed in the
       main panel.  The purpose of this page is to examine log files from the most recent fit or
       from previous fits.  These log files can be read individually or reports can be generated
       based on their contents.

       When this page is displayed, each fit is entered into the list box on the left side of the
       page.  Double clicking the left mouse button on a fit in the listbox will display that
       fit's raw log file.  Right clicking on a fit will post a menu with choices for displaying
       that fit's log file in raw, quick, or columnar form or for performing some other tasks
       related to that fit.

       Much more interesting than displaying the log files, though, is to generate reports on the
       log files.  Near the top of the page is a combo box for selecting among the parameters on
       the Guess, Def, Set page.  Choosing one, then clicking on the "Write report" button will
       find extract that parameters best-fit value and uncertainty from each log file.  This
       feature allows you to track the evolution of individual fitting parameters as you develop
       your fitting model.

       The combo box containing the names of the fitting parameters is filled using the contents
       of the Guess, Def, Set page.  Sometimes it may be useful instead to fill the combo box
       with the parameter names extracted from a log file.  This would be useful, for instance,
       for examining a parameter that is was used at one point, but is no longer on the GDS page
       or has been made into a skip parameter (and so is not included in the combo box by
       default).  To do this, right click on a fit and select the "Get parameter list" item.

       Some modifications can be made to the reports generated by the log viewer.  Clicking on
       the "Compute the average value" button tells Artemis to compute the arithmetic mean and
       standard deviation of the parameter from the values extracted from the various log files.
       These will be displayed in the header of the report.

       Clicking on the "Fit Einstein temperature" button will tell Artemis to fit sigma^2 data to
       a model consisting of a single frequency oscillator plus a constant offset.  The report
       header will then contain the best fit values and uncertainties for the characteristic
       temperature and constant offset.  This calculation will only happen is the figures of
       merit for the selected log files are temperatures and the best fit values for the chosen
       parameter are reasonable sigma^2 values.  This function makes a series of checks on the
       figures of merit and best fit values to determine if they seem to be data appropriate for
       this calculation.  These heuristics can be tuned by setting parameters in the logview
       section of the preferences dialog.

       The final item in the context menu that is displayed when right clicking on an item in the
       log files list is an option to restore that fitting model.  Among the information that is
       saved every time a fit is made is a complete description of the fitting model, including
       which data file is being fit, the complete list of Feff path used, and all fitting, data,
       and path parameters.  This feature allow you to revert Artemis to the state it was in when
       a past fit was made.  When you do this reversion, Artemis will clear out the contents of
       the Data and Paths List and then recreate the project in the form of the selected fitting
       model.  This is more that just a change of parameter values.  Artemis keeps track of all
       data and Feff paths used throughout the course of the project and can restore even fits
       that are significantly different from the current fit.

       Importing Athena project data || Output files || Artemis project files ||

ARTEMIS: Plotting Data

       ARTEMIS - Plotting data

       Plots in Artemis are made using the selected items in the Data and Paths List, which are
       the ones highlighted in orange.  See the main document section for an explanation of how
       to selected items for plotting.

       At the top of the plot panel are three big, red buttons.  One is for making a plot in
       k-space, one is for R-space, and the third is for q-space (i.e. back-transformed k-space).

   k-Weighting
       Below the plot buttons are a set of radiobuttons for setting the k-weight to use in the
       plots.  The k-weight chosen will be used to weight a plot in k-space or to weight data for
       Fourier transforming.  The same k-weight is used for each selected item.  The button
       marked "kw" needs some explanation.  When this button is chosen, the k-weight to use in
       the plot will be determined from the data being plotted.  If the arbitrary k-weight
       enabled for the data set,the value for the arbitrary k-weight will be used, other wise the
       smallest k-weight value enabled will be used.  There are two reason to use the "kw"
       button.  One is to plot using your arbitrary weight.  The other is to make a plot of two
       or more data sets using a different k-weight for each data set.

       Note that these k-weight controls are unrelated to the controls which set the k-weight
       used in the fit.  K-weighting for fitting and plotting are controlled independently.

   Selecting What Gets Plotted
       Below the k-weight radiobuttons are menus for choosing which part of the complex functions
       chi(R) or chi(q) to plot.  Plots involving multiple parts of the complex functions (e.g.
       real+envelope) are not currently possible.

       Below these menus are three checkbuttons used for plotting the Fourier transform window,
       the background function, and the residual.  If the window button is pressed, the
       appropriate window function will be plotted in any plot.  The background and residual
       functions are only plotted if one of the selected items is a fit.  The background will
       only be plotted if a background corefinement was made for that fit.  If a fit is not among
       the selected items, the background and residual will not be plotted.  Note that a plot
       with more than one selected fit may be quite confusing if the background or residual
       buttons are depressed since the background and residual will be plotted for each fit.

       The ranges over which the plot will be made in the three spaces are controlled by the
       three sets of entry boxes.

   Extra Plotting Features
       The two additional tabs in the plotting panel contain the controls for the following
       utilities:

       Indicators

       Indicators are vertical bars that can be placed at user-chosen locations in k-, R-, or
       q-space.  These indicators will get displayed every time a plot is made.  The idea is that
       indicators are a guide to the eye, drawing attention to a place of interest as the data
       being plotted changes.

       Indicators selected in either k- or q-space will be plotted in both k- and q-space, but
       not in R-space.  Likewise, indicators selected in R-space will not be plotted in k- or
       q-space.

       Several characteristics of the indicators, including the number, the linetype, and the
       color, can be set in the Plot section of the preferences dialog.

       The indicators play well with each of the plotting options described below.

       Stacking

       Stacking refers to a vertical displacement the various traces.  This is most useful for
       plotting the various path contributions in k-space, but is sometimes useful in other kinds
       of plots as well.  Stacking requires three parameters which are set in the stacking
       notecard.  The first control is series of radio buttons for choosing whether stacking
       happens in k-space, always, or never.  If the k-space option is chosen, then q-space plots
       of the real or imaginary parts will also be stacked.  (Basically, the "k-space" choice
       refers to any wiggly function of wavenumber.)  The other two controls set the initial
       offset value and the increment between staces.

       Inverting

       Inverting is a useful tool for displaying the path contributions in "|chi(R)|" plots.
       When this is selected, the "|chi(R)|" from any paths included in the plot will be
       multiplied by -1 so that they stick down below the zero-axis.  Hopefully this kind of plot
       help reduce clutter while still helping to show which paths contribut where.  The
       radiobuttons on this notecard allow you choose between never inverting, inverting
       "|chi(R)|", or inverting both "|chi(R)|" and "|chi(q)|".  The real and imaginary parts in
       R- or q-space are never inverted.  chi(k) is also never inverted.  Inverting is turned off
       whenever stacking is selected and would effect the current plot (i.e. you cannot stack and
       invert at the same time).

       Data set offsets

       This feat ure is useful for multiple data set plots.  This is similar to stacking in that
       the parameter denotes a vertical offset for use i the plot.  Each trace associated with a
       particular data set is plotted at the same lavel, but the data sets will be offset by the
       amount specified by this control.  This provides a way of simultaneously visualizing all
       parts of a multiple data set fit.  Negative values are recommended, with a negative
       offset, the traces will be plotted in the same order from top to bottom as in the plot
       legend.

       Stacking is disabled when data set offsets are used.  Inverting is used with data set
       offsets, although I think this results in confusing plots.

       Palettes || Using the Data and Paths List || =head1 ARTEMIS: Editing Math Expressions

       ARTEMIS - Editing math expressions

       The math expression editing dialog is a way of setting path parameter math expressions for
       many paths at once.  It works on a given path parameter, e.g. it sets e0 or sigma^2 for
       many paths but does not touch other path parameters.  This dialog is available in two
       different context menus.  If you right click on a path parameter label on the path page
       and selection "Edit for many paths", then the dialog will pop up for editing that
       parameter.  If you right click on an entry on the Feff interpretation page and select the
       "Edit path parameters" cascade, then select a path parameter, the dialog will pop up for
       editing that parameter.

   Operation of the dialog
       The dialog is fairly simple.  At the top is a text entry box for typing in your math
       expression.  Below that are various radiobuttons for specifying how to apply the math
       expression to the various paths in your project.  The options are:

       1.  Add the math expression to every path in the current Feff calculation.

       2.  Add the math expression to every path in the each Feff calculation.

       3.  Add the math expression to every path in the each Feff calculation associated with the
           current data set.

       4.  Add the math expression to selected paths (i.e. the ones highlighted in orange in the
           Data and Paths list).

   Tokens
       You can write your math expressions using token.  Tokens are short character strings which
       will be replaced by path-specific information as the math expression is applied to each
       path.  The tokens are:

       %i  The path index from the Feff calculation.  This is actually computed from the name of
           the `feffNNNN.dat' file from the Feff calculation.  For instance, if the file is
           `feff0029.dat', then %i will expand to 29.

       %I  The path index from the Feff calculation, padded to fill four characters.  For
           instance, if the file is `feff0029.dat', then %I will expand to 0029.

       %r  The effective path length (or "reff") from the Feff calculation for the path.

       %d  The degeneracy of the path.

       %D  A template for the Debye function.  This always expands to the string
           "debye(temp,thetad)" and may need be edited after the fact to use the correct variable
           names.  This is offered because the author finds it hard to remember the order of the
           arguments to the Debye function.

       %E  A template for the Einstein function.  This always expands to the string
           "eins(temp,thetae)" and may need be edited after the fact to use the correct variable
           names.  This is offered because the author finds it hard to remember the order of the
           arguments to the Einstein function.

ARTEMIS: Automated First Shell Theory

       ARTEMIS - Automated first shell theory

       Sometimes thinking about a fitting model is more than a problem merits.  You just want a
       quick 'n' dirty stab at the first shell -- perhaps to measure the centroid of the
       distribution, perhaps to tell if a sample is 4- or 6-coordinated.  Whatever.

       Artemis is not extremely well suited to rapid-fire, first shell analysis.  By design,
       Artemis tends to force the user to slow down and think hard about every step.  Artemis is
       powerful, but she ain't simple.

       The quick first shell (QFS) theory tool is an attempt at addressing this shortcoming.  It
       works like this:

       1.  Import some data.  Set the Fourier transform and fitting parameters to suitable
           values.  Specifically, be sure to set the fitting range such that it encloses the
           first peak of the data.

       2.  Select "Quick first shell theory" from the Theory menu.  This will display the QFS
           dialog.

       3.  The QFS dialog provides spaces for selecting the parameters for a simple first shell
           theory.  These include the atomic species of the absorber and the scatterer, the
           absorption edge of the experiment, the approximate distance between the absorber and
           scatterer, and the coordination geometry to use in the Feff calculation.

           Currently the following coordination geomatries are available:

           •   4-coordinate crystal

           •   6-coordinate crystal

           •   octahedral molecule

           •   tetrahedral molecule

           •   square-planar molecule

           The QFS theory is probably not highly sensitive to the choice of coordination
           geometry.  Since the unknown sample is probably not well described by any of these
           geometries, they are all merely approximations for use in a quick 'n' dirty fit.

       4.  Once you have set up the parameters for the QFS theory, click the "Do it!" button.
           This will step through the following without pausing:

           a.  Build an input file for the Feff calculation

           b.  Run Feff

           c.  Import the first path from the Feff calculation

           d.  Create a set of guess parameters for the amplitude, the sigma^2, the e0, and the
               delta R.  Also created are set parameters for the third and fourth cumulants, but
               they are set to zero.  These higher cumulant set parameters are created to make it
               easy to consider higher cumulants in subsequent fits merely by changing them from
               set to guess.

       If you have a mixed first shell, you might choose to repeat steps 2 through 4 two or more
       times.

       At the end of this sequence, you are left with Artemis in its normal state.  You may need
       to adjust the parameters used in the fit.  The QFS dialog is really just a tool for
       initially setting up the project.  It in no way changes the normal operation of Artemis.

       If you import data from an Athena project file, the species of the absorber and the edge
       will be set correctly when you start the dialog.

       The Menubar || The preferences dialog ||

REFERENCES

       Here are the relevant URLs:

       IFEFFIT
             http://cars.uchicago.edu/ifeffit

       PGPLOT
             http://www.astro.caltech.edu/~tjp/pgplot/

       Perl
             http://www.perl.com

       perl/Tk
             http://www.lehigh.edu/~sol0/ptk/

MISSING FEATURES

       You betcha!

WHAT'S IN A NAME?

       Artemis was the goddess of the hunt, an apt metaphor doing EXAFS analysis. ARTemis is also
       a pun on the nature of EXAFS analysis that works in English and in the romance languages.

AUTHOR

         Bruce Ravel <bravel@anl.gov> (c) 2001 - 2006
         http://cars.uchicago.edu/~ravel/software/

         Ifeffit is copyright (c) 1992 - 2006 Matt Newville
         newville@cars.uchicago.edu
         http://cars.uchicago.edu/ifeffit/