master: fun_construct.hpp: x -> ax , y -> ay , improve Sequence Const…

…ructor discussion.

CMakeLists.txt

@@ -16,7 +16,7 @@ IF( POLICY CMP0054 )
 ENDIF( POLICY CMP0054 )
 #
 # cppad_version is used by version.sh to get the version number.
-SET(cppad_version "20240315")
+SET(cppad_version "20240316")
 SET(cppad_url          "https://coin-or.github.io/CppAD" )
 SET(cppad_description  "Differentiation of C++ Algorithms" )
 IF( NOT DEFINED CMAKE_BUILD_TYPE)

appendix/whats_new/2024.xrst

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
-# SPDX-FileCopyrightText: Bradley M. Bell <[email protected]>
+# SPDX-FileCopyrightText: Bradley M. Bell  <[email protected]>
 # SPDX-FileContributor: 2003-24 Bradley M. Bell
 # ----------------------------------------------------------------------------
 
@@ -30,6 +30,13 @@ Release Notes for 2024
 mm-dd
 *****
 
+03-16
+=====
+The :ref:`ADFun constructor<fun_construct-name>` was changed to use
+*ax* instead of *x* , and *ay* instead of *y* , for AD values.
+In addition, the :ref:`fun_construct@Sequence Constructor` discussion
+was improved. 
+
 03-15
 =====
 #. The user's choice of :ref:`ta_parallel_setup@in_parallel` routine

include/cppad/core/dependent.hpp

@@ -14,15 +14,17 @@ Syntax
 ******
 *f* . ``Dependent`` ( *x* , *y* )
 
-Purpose
-*******
-Stop recording and the AD of *Base*
+Stop Recording
+**************
+The call stops the recording and the AD of *Base*
 :ref:`operation sequence<glossary@Operation@Sequence>`
 that started with the call
 
    ``Independent`` ( *x* )
 
-and store the operation sequence in *f* .
+Store Operation Sequence
+************************
+This call also stores the operation sequence in *f* .
 The operation sequence defines an
 :ref:`glossary@AD Function`
 

include/cppad/core/fun_construct.hpp

@@ -7,7 +7,7 @@
 /*
 {xrst_begin fun_construct}
 {xrst_spell
-   of of
+   versa
 }
 
 Construct an ADFun Object and Stop Recording
@@ -16,7 +16,7 @@ Construct an ADFun Object and Stop Recording
 Syntax
 ******
 
-| ``ADFun`` < *Base* > *f* ( *x* , *y* );
+| ``ADFun`` < *Base* > *f* ( *ax* , *ay* );
 | ``ADFun`` < *Base* > *f*
 | *f* . ``swap`` ( *g* )
 | ``f`` = ``g``
@@ -35,31 +35,31 @@ It can then be used to calculate derivatives of the corresponding
 
 where :math:`B` is the space corresponding to objects of type *Base* .
 
-x
-*
-If the argument *x* is present, it has prototype
+ax
+**
+If the argument *ax* is present, it has prototype
 
-   ``const`` *ADVector* & *x*
+   ``const`` *ADVector* & *ax*
 
 It must be the vector argument in the previous call to
 :ref:`Independent-name` .
 Neither its size, or any of its values, are allowed to change
 between calling
 
-   ``Independent`` ( *x* )
+   ``Independent`` ( *ax* )
 
 and
 
-   ``ADFun`` < *Base* > *f* ( *x* , *y* )
+   ``ADFun`` < *Base* > *f* ( *ax* , *ay* )
 
-y
-*
-If the argument *y* is present, it has prototype
+ay
+**
+If the argument *ay* is present, it has prototype
 
-   ``const`` *ADVector* & *y*
+   ``const`` *ADVector* & *ay*
 
-The sequence of operations that map *x*
-to *y* are stored in the ADFun object *f* .
+The sequence of operations that map *ax*
+to *ay* are stored in the ADFun object *f* .
 
 ADVector
 ********
@@ -84,38 +84,38 @@ returns the value zero (see :ref:`fun_property@size_var` ).
 
 Sequence Constructor
 ********************
-The sequence constructor
+The following constructor stores the current ``AD`` < *Base* > operation
+sequence in *f* :
 
-   ``ADFun`` < *Base* > *f* ( *x* , *y* )
+   ``ADFun`` < *Base* > *f* ( *ax* , *ay* )
 
-creates the ``AD`` < *Base* > object *f* ,
-stops the recording of AD of *Base* operations
-corresponding to the call
-
-   ``Independent`` ( *x* )
-
-and stores the corresponding operation sequence in the object *f* .
-It then stores the zero order Taylor coefficients
-(corresponding to the value of *x* ) in *f* .
-This is equivalent to the following steps using the default constructor:
+To be specific, it is equivalent to the following 
+steps using the default constructor:
 
 #. Create *f* with the default constructor
 
       ``ADFun`` < *Base* > *f* ;
 
-#. Stop the tape and storing the operation sequence using
+#. Stop the recording and store the operation sequence using
 
-      *f* . ``Dependent`` ( *x* , *y* );
+      *f* . ``Dependent`` ( *ax* , *ay* );
+
+   see :ref:`Independent@Start Recording` ,
+   :ref:`Dependent@Stop Recording` , and
+   :ref:`Dependent@Store Operation Sequence` .
 
-   (see :ref:`Dependent-name` ).
 #. Calculate the zero order Taylor coefficients for all
    the variables in the operation sequence using
 
-      *f* . ``Forward`` ( *p* , *x_p* )
+      *y* = *f* . ``Forward`` ( 0 , *x* )
+
+   see :ref:`forward_zero-name`.
+   Here *x* and *y* are :ref:`simple vectors <SimpleVector-name>`
+   with elements of type *Base* and the elements of *x*
+   are equal to the corresponding elements in *ax*.
 
-   with *p* equal to zero and the elements of *x_p*
-   equal to the corresponding elements of *x*
-   (see :ref:`Forward-name` ).
+#. If NDEBUG is not defined, *y* is checked to make sure it's elements are 
+   nearly equal to the corresponding values in *ay* .
 
 Copy Constructor
 ****************
@@ -132,8 +132,7 @@ swap
 ****
 The swap operation *f* . ``swap`` ( *g* ) exchanges the contents of
 the two ``ADFun`` < *Base* > functions; i.e.,
-*f* ( *g* ) before the swap is identical to
-*g* ( *f* ) after the swap.
+*f* before the swap is identical to *g* after the swap and vise versa.
 
 Assignment Operator
 *******************
@@ -150,8 +149,7 @@ and any information originally in *g* is lost.
 
 Move Semantics
 ==============
-In the special case where *f* is a temporary object
-(and enough C++11 features are supported by the compiler)
+In the special case where *f* is a temporary object,
 this assignment will use move semantics.
 This avoids the overhead of the copying all the information from
 *f* to *g* .
@@ -180,11 +178,11 @@ Parallel Mode
 The call to ``Independent`` ,
 and the corresponding call to
 
-   ``ADFun`` < *Base* > *f* ( *x* , *y* )
+   ``ADFun`` < *Base* > *f* ( *ax* , *ay* )
 
 or
 
-   *f* . ``Dependent`` ( *x* , *y* )
+   *f* . ``Dependent`` ( *ax* , *ay* )
 
 or :ref:`abort_recording-name` ,
 must be preformed by the same thread; i.e.,

user_guide.xrst

@@ -13,7 +13,7 @@
 
 {xrst_comment BEGIN: Before changing see new_release.sh and check_version.sh}
 
-cppad-20240315: CppAD User's Manual
+cppad-20240316: CppAD User's Manual
 ###################################
 
 .. image:: {xrst_dir coin.png}