.. Athena document is copyright 2016 Bruce Ravel and released under The Creative Commons Attribution-ShareAlike License http://creativecommons.org/licenses/by-sa/3.0/ .. role:: guess .. role:: def .. role:: set .. role:: lguess .. role:: restrain .. role:: skip .. role:: after .. role:: penalty .. role:: merge Guess/Def/Set Parameters ======================== In :demeter:`demeter`, every part of a fit is an object. The same is true of the parameters of the fit. A new guess parameter is defined like so: .. code-block:: perl my $new_param = Demeter::GDS->new(gds => 'guess', name => 'deltar', mathexp => 0.0); Every GDS object requires specifying these three attributes. The type of parameter, denoted by the ``gds`` attribute, is explained in detail below. The ``name`` is the string that identifies the parameter and is used in the math expressions for path parameters and other kinds of GDS objects. In the case of a guess parameter, the ``mathexp`` is the initial value of the parameter to be used at the start of the fit. For other kinds of GDS ojbects, the ``mathexp`` attributes might take an actual math expression, i.e. a character string to be interpreted and evaluated by :demeter:`ifeffit`. ``gds``, ``name``, and ``mathexp`` are normal attributes of the GDS object and can be treated like attributes of any object. So, for instance, if you wish to change the starting value of the ``deltar`` parameter, you can do like so: .. code-block:: perl my $new_param = mathexp(0.025); Here is another example, this time for a def parameter that takes an actual math expression: .. code-block:: perl my $new_param = Demeter::GDS->new(gds => 'def', name => 'c', mathexp => '(a + b) * tan(angle/2) / (a - b)'); Simplified interface -------------------- Although the syntax for the GDS object is identical to the syntax for all other :demeter:`demeter` objects, it seems somehow more cumbersome in this case |nd| particularly for anyone who goes back to the good ol' days of writing :file:`feffit.inp` files. As a bit of syntactic sugar, the :demeter:`demeter` base class offers a method that takes a character string as its sole argument. That character string is parsed the same way as a parameter definition in a :file:`feffit.inp` file. .. code-block:: perl my $new_param = $any_object->simpleGDS('guess deltar = 0.0'); The ``simpleGDS`` simply parses the string and uses that to create a GDS object, which it then returns. The normal and simple syntax can be used interchangeably and for all GDS types. They are completely equivalent. Parameter types --------------- There are 9 types of GDS parameters, that is, 9 possible values for the ``gds`` attribute. Three of these will be familiar to users of :demeter:`ifeffit` and :demeter:`artemis`, the others are newly introduced by :demeter:`demeter`. :guess:`guess` A parameter which is varied in a fit. :def:`def` A parameter whose math expression is continuously updated throughout the fit. :set:`set` A parameter which is evaluated at the beginning of the fit and remains unchanged after that. :lguess:`lguess` A :lguess:`locally guessed` parameter. In a multiple data set fit, this will be expanded to one :guess:`guess` parameter per data set. See `the section on local guess parameters <../lgcv.html>`__ for more details. :restrain:`restrain` A :restrain:`restrain` parameter is defined in an :demeter:`ifeffit` script as a :def:`def` parameter but is used as a :restrain:`restraint` in the call to :demeter:`ifeffit`'s ``feffit`` command. In a multiple data set fit, all :restrain:`restraints` are defined in the first call to the ``feffit`` command. :skip:`skip` A :skip:`skip` is a parameter that is defined but then ignored. Setting a variable to a :skip:`skip` is useful in a GUI as a way of :quoted:`commenting out` a parameter without removing it from the fitting project. :after:`after` This is like a :def:`def` parameter, but is not used in the fitting model and only evaluated when the fit finishes. It is then reported in the log file. :penalty:`penalty` This is like a :def:`def` parameter, but is used as a user-defined subtraction from the `happiness parameter <../fit/happiness.html>`__, which is evaluated at the end of the fit. *This is not currently implemented.* :merge:`merge` A merge is the type given to a parameter that cannot be unambiguously resolved when two Fit objects are merged into a single Fit object. A fit cannot proceed until all merge parameters are resolved. It is unlikely that a variable would ever be declared as a merge by a user, although if a user script makes use of any of :demeter:`demeter`'s (*as yet unimplemented*) project merging features, it will certainly be necessary to resolve a merge parameter by renaming it globally and resetting the ``gds`` attribute. .. todo:: :penalty:`penalty` and :merge:`merge` types are currently unimplemented. Reporting on and annotating GDS parameters ------------------------------------------ :demeter:`demeter` provides several ways of examining GDS objects. Along with direct examination of the attributes, such as ``bestfit`` and ``error``, there are several kinds of textual reports on the state of the GDS object and its parameter. This example shows three of these: .. code-block:: perl my $amp_param = Demeter::GDS -> new(gds => 'guess', name => 'amp', mathexp => 1); ## ... some time later, after a fit ... print $amp_param -> note, $/; print $amp_param -> report, $/; print $amp_param -> full_report, $/; The ``note`` attribute contains the annotation. By default, the annotation for a :guess:`guess` parameter is set after a fit using the best fit value and the uncertainty, as shown below. For most other parameter types, annotation is set using the evaluation of the parameter as stored in the ``bestfit`` attribute. .. code-block:: text amp: 0.98096480 +/- 0.08074672 There is the option of annotating a parameter to a user-defined string. When explicitly set, the automatic annotation after a fit finishes does not happen. The purpose of the annotation is to store a description of the purpose served in a fitting model by a parameter. In the example used here, you might annotate the parameter like so: .. code-block:: perl $amp_param -> note("This parameter represents S_0^2."); The ``report`` method is used after a fit to write out parameter results to a log file. It looks like this, giving the best fit value, the uncertainty, and the initial guess in brackets: .. code-block:: text amp = 0.98096480 # +/- 0.08074672 [1] The ``full_report`` writes out a more complete description of the state of the object. It looks like this: .. code-block:: text amp guess parameter math expression: 1 evaluates to 0.98096480 +/- 0.08074672 annotation: "This parameter represents S_0^2."