..
   Artemis document is copyright 2016 Bruce Ravel and released under
   The Creative Commons Attribution-ShareAlike License
   http://creativecommons.org/licenses/by-sa/3.0/


FSPath object
=============

Sometimes :demeter:`demeter` is just too much. A simple, first shell,
single scattering problem should have a simple solution. The FSPath,
or :demeter:`first shell path`, is intended to be that simple
solution.

You provide the element symbol of the absorber and scatterer, their
distance apart, and the absorption edge. :demeter:`demeter` will then
construct a simple :demeter:`feff` input file, run :demeter:`feff`,
return the single scattering path at the specified distance, and even
create a set of guess parameters for you. It's pretty simple. In this
example, we create an oxygen scattering shell at 2 |AA| around an iron
absorber and use it to fit some iron oxide data contained in an
:demeter:`athena` project file.

.. code-block:: perl
   :linenos:

    #!/usr/bin/perl
    use Demeter;
    my $prj = Demeter::Data::Prj->new(file => 'FeO.prj');
    my $data = $prj -> record(1);
    my $fspath = Demeter::FSPath->new(abs       => 'Fe',
                                      scat      => 'O',
                                      edge      => 'K',
                                      distance  => 2.0,
                                      data      => $data,
                                      workspace => "/path/to/work/space",
                                     );
    my $fit = Demeter::Fit->new(data  => [$data_object],
                                paths => [$fspath],
                                gds   => $fspath->gds);
    ## now do something with the results of the fit ...

When the object if created, :demeter:`demeter` will construct a
:file:`feff.inp` for a simple cubic structure containing the absorber
and scatterer. The lattice constant of this notional crystal is such
that the first neighbor distance is as specified. The edge can be
asserted explicitly, but it can usually be guessed from the atomic
species of the absorber |nd| the K edge is assumed for elements lighter
than La, otherwise the L\ :sub:`III` edge is assumed.

Like a normal Path, the FSPath must be associated with a Data object
via its ``data`` attribute.  Because, a :demeter:`feff` calculation is
done behind the scenes, a ``workspace`` attribute must be specified so
that :demeter:`demeter` has a place to perform the calculation.

All the details of the :demeter:`feff` calculation are handled
automatically. The FSPath will always be up-to-date for use in a plot
or a fit.

Also behind the scenes, a set of guess parameters is created. For the
example shown, these parameters will be named ``aa_fe_o``, ``ee_fe_o``,
``dr_fe_o``, and ``ss_fe_o``. The second and third parts of those names
are taken from the element symbols of the abosorber and scatterer. The
``new`` method can also take ``use_third`` and ``use_fourth`` as
arguments.  When true, additional guess parameters will be made to
represent the third and fourth cumulants and will be called ``c3_fe_o``
and ``c4_fe_o``. These parameters are then used as the math expressions
for the appropriate pathparameters of the path. If you choose to use
this simple parameterization of the FSPath, you are then ready to begin
fitting.

The ``gds`` method, shown at line 14, returns a list containing the GDS
objects associated with the automatically generated parameters. Because
the FSPath is derived from the Path object, it behaves in every other
way like a normal Path object.  Thus, if you want to overwrite the path
parameter math expressions, simply set them the way you would for any
Path object.

.. code-block:: perl

   $fspath -> set(s02 => '(1-x)*amp', enot=>'enot_o');

The values of the ``scat`` and ``abs`` attributes can be the one- or
two-letter symbols, the full English names of the elements, or the Z
number.  The ``absorber`` and ``scatterer`` attributes are filled
automatically with the resolved one- or two-letter atomic symbols.

There are a couple more methods involved with the automatically
generated parameters.  The ``parameter`` method is used to obtain the
GDS objects that were automatically created.  It takes a single
argument for identifying the parameter being queried.  Here is every
possible example of its use. In each case, the reference to the GDS
object is returned.

.. code-block:: perl

      my $amp_gds    = $fspath->parameter('s02');
      my $e0_gds     = $fspath->parameter('e0');
      my $delr_gds   = $fspath->parameter('delr');
      my $sigma2_gds = $fspath->parameter('sigma2');
      my $third_gds  = $fspath->parameter('third');
      my $fourth_gds = $fspath->parameter('fourth'); 

Finally, the ``unset_parameters`` method is used to clear the
autogenerated path parameters, setting them all literally to 0 |nd|
except for s02, which is set literally to 1.  This is useful in a
situation where you wish to use the quick first shell scattering path
in some other context than the quick first shell fit.