--- name: "sc_Function" section: "3" platform: "linux" package: "libsc-doc" version: "2.3.1-22" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/sc_Function" --- # sc\_Function(3) The Function class is an abstract base class that, given a set of coordinates, will compute a value and possibly a gradient and hessian at that point. ## NAME sc::Function - The **Function** class is an abstract base class that, given a set of coordinates, will compute a value and possibly a gradient and hessian at that point. ## SYNOPSIS `#include ` Inherits **sc::SavableState**, and **sc::Compute**. Inherited by **sc::MolecularEnergy**, and **sc::Volume**. ### Public Member Functions **Gradient Members**\ These are analogous to the routines that deal with values, but work with gradients instead. virtual **RefSCVector** **gradient** ()\ int **gradient\_needed** () const\ int **do\_gradient** (int)\ virtual void **set\_desired\_gradient\_accuracy** (double)\ virtual double **actual\_gradient\_accuracy** () const\ virtual double **desired\_gradient\_accuracy** () const\ **AccResultRefSCVector** & **gradient\_result** ()\ **Hessian Members**\ These are analogous to the routines that deal with values, but work with the hessian instead. virtual **RefSymmSCMatrix** **hessian** ()\ int **hessian\_needed** () const\ int **do\_hessian** (int)\ virtual void **set\_desired\_hessian\_accuracy** (double)\ virtual double **actual\_hessian\_accuracy** () const\ virtual double **desired\_hessian\_accuracy** () const\ **AccResultRefSymmSCMatrix** & **hessian\_result** ()\ virtual void **guess\_hessian** (**RefSymmSCMatrix** &)\ **Compute** a quick, approximate hessian. virtual **RefSymmSCMatrix** **inverse\_hessian** (**RefSymmSCMatrix** &)\ virtual int **value\_implemented** () const\ Information about the availability of values, gradients, and hessians. virtual int **gradient\_implemented** () const\ virtual int **hessian\_implemented** () const\ virtual void **set\_x** (const **RefSCVector** &)\ Set and retrieve the coordinate values. **RefSCVector** **get\_x** () const\ const **RefSCVector** & **get\_x\_no\_copy** () const\ virtual **Ref**\< **NonlinearTransform** \> **change\_coordinates** ()\ An optimizer can call change coordinates periodically to give the function an opportunity to change its coordinate system. virtual void **print** (std::ostream &=**ExEnv::out0**()) const\ Print information about the object. ### Protected Member Functions **Update Members**\ Update the various computable results. virtual void **set\_value** (double)\ virtual void **set\_gradient** (**RefSCVector** &)\ virtual void **set\_hessian** (**RefSymmSCMatrix** &)\ virtual void **set\_matrixkit** (const **Ref**\< **SCMatrixKit** \> &)\ Set the **SCMatrixKit** that should be used to construct the requisite vectors and matrices. virtual void **set\_dimension** (const **RefSCDimension** &)\ ### Protected Attributes **Ref**\< **SCMatrixKit** \> **matrixkit\_**\ Used to construct new matrices. **RefSCVector** **x\_**\ The variables. **RefSCDimension** **dim\_**\ The dimension of x\_. **AccResultdouble** **value\_**\ The value of the function at x\_. **AccResultRefSCVector** **gradient\_**\ The gradient at x\_. **AccResultRefSymmSCMatrix** **hessian\_**\ The hessian at x\_. ### Accuracy Setting Members Set the accuracies with which the various computables have been computed. virtual void **set\_actual\_value\_accuracy** (double)\ virtual void **set\_actual\_gradient\_accuracy** (double)\ virtual void **set\_actual\_hessian\_accuracy** (double)\ **RefSCVector** & **get\_x\_reference** ()\ Get read/write access to the coordinates for modification. void **do\_change\_coordinates** (const **Ref**\< **NonlinearTransform** \> &)\ Change the coordinate system and apply the given transform to intermediates matrices and vectors. **Function** ()\ **Function** (**StateIn** &)\ **Function** (const **Function** &)\ **Function** (const **Ref**\< **KeyVal** \> &, double funcacc=DBL\_EPSILON, double gradacc=DBL\_EPSILON, double hessacc=DBL\_EPSILON)\ The keyval constructor reads the following keywords: virtual **~Function** ()\ **Function** & **operator=** (const **Function** &)\ **Ref**\< **SCMatrixKit** \> **matrixkit** () const\ Return the **SCMatrixKit** used to construct vectors and matrices. **RefSCDimension** **dimension** () const\ Return the **SCDimension** of the problem. virtual void **save\_data\_state** (**StateOut** &)\ Save the base classes (with save\_data\_state) and the members in the same order that the **StateIn** CTOR initializes them. virtual double **value** ()\ Return the value of the function. int **value\_needed** () const\ Returns nonzero if the current value is not up-to-date. int **do\_value** (int)\ If passed a nonzero number, compute the value the next time **compute()** is called. **AccResultdouble** & **value\_result** ()\ virtual void **set\_desired\_value\_accuracy** (double)\ Set the accuracy to which the value is to be computed. virtual double **actual\_value\_accuracy** () const\ Return the accuracy with which the value has been computed. virtual double **desired\_value\_accuracy** () const\ Return the accuracy with which the value is to be computed. ### Additional Inherited Members ## Detailed Description The **Function** class is an abstract base class that, given a set of coordinates, will compute a value and possibly a gradient and hessian at that point. ## Constructor & Destructor Documentation ### sc::Function::Function (const Ref\< KeyVal \> &, double funcacc = `DBL_EPSILON`, double gradacc = `DBL_EPSILON`, double hessacc = `DBL_EPSILON`) The keyval constructor reads the following keywords: - `matrixkit` Gives a **SCMatrixKit** object. If it is not specified, a default **SCMatrixKit** is selected. - `value_accuracy` Sets the accuracy to which values are computed. The default is the machine accuracy. - `gradient_accuracy` Sets the accuracy to which gradients are computed. The default is the machine accuracy. - `hessian_accuracy` Sets the accuracy to which hessians are computed. The default is the machine accuracy. ## Member Function Documentation ### virtual Ref\< NonlinearTransform \> sc::Function::change\_coordinates ()` [virtual]` An optimizer can call change coordinates periodically to give the function an opportunity to change its coordinate system. A return value of 0 means the coordinates were not changed. Otherwise, a transform object to the new coordinate system is return. The function object applies the transform to any objects it contains. This will obsolete the function data. Reimplemented in **sc::MolecularEnergy**. ### int sc::Function::do\_value (int) If passed a nonzero number, compute the value the next time **compute()** is called. Return a nonzero number if the value was previously to be computed. ### virtual void sc::Function::guess\_hessian (RefSymmSCMatrix &)` [virtual]` **Compute** a quick, approximate hessian. Reimplemented in **sc::MolecularEnergy**. ### virtual RefSymmSCMatrix sc::Function::hessian ()` [virtual]` Reimplemented in **sc::MolecularEnergy**. ### virtual void sc::Function::print (std::ostream & = ExEnv::out0`()`) const` [virtual]` Print information about the object. Reimplemented from **sc::DescribedClass**. Reimplemented in **sc::MolecularEnergy**, **sc::TaylorMolecularEnergy**, **sc::Wavefunction**, **sc::CLKS**, **sc::HSOSKS**, **sc::UKS**, **sc::MBPT2**, **sc::MBPT2\_R12**, **sc::PsiWavefunction**, **sc::CLHF**, **sc::CLSCF**, **sc::HSOSHF**, **sc::HSOSSCF**, **sc::OSSHF**, **sc::OSSSCF**, **sc::SCF**, **sc::TCHF**, **sc::TCSCF**, **sc::UHF**, **sc::UnrestrictedSCF**, **sc::OneBodyWavefunction**, **sc::SphereShape**, and **sc::UncappedTorusHoleShape**. ### virtual void sc::Function::save\_data\_state (StateOut &)` [virtual]` Save the base classes (with save\_data\_state) and the members in the same order that the **StateIn** CTOR initializes them. This must be implemented by the derived class if the class has data. Reimplemented from **sc::SavableState**. Reimplemented in **sc::MolecularEnergy**, **sc::SumMolecularEnergy**, **sc::TaylorMolecularEnergy**, **sc::CLKS**, **sc::HSOSKS**, **sc::UKS**, **sc::MBPT2**, **sc::MP2BasisExtrap**, **sc::MBPT2\_R12**, **sc::PsiWavefunction**, **sc::PsiSCF**, **sc::PsiCCSD**, **sc::PsiCCSD\_T**, **sc::CLHF**, **sc::CLSCF**, **sc::HSOSHF**, **sc::HSOSSCF**, **sc::OSSHF**, **sc::OSSSCF**, **sc::SCF**, **sc::TCHF**, **sc::TCSCF**, **sc::UHF**, **sc::UnrestrictedSCF**, **sc::ExtendedHuckelWfn**, **sc::OneBodyWavefunction**, **sc::HCoreWfn**, and **sc::Wavefunction**. ### virtual void sc::Function::set\_desired\_value\_accuracy (double)` [virtual]` Set the accuracy to which the value is to be computed. Reimplemented in **sc::UnrestrictedSCF**, and **sc::OneBodyWavefunction**. ### virtual void sc::Function::set\_gradient (RefSCVector &)` [protected]`, ` [virtual]` Reimplemented in **sc::MolecularEnergy**. ### virtual void sc::Function::set\_x (const RefSCVector &)` [virtual]` Set and retrieve the coordinate values. Reimplemented in **sc::MolecularEnergy**, **sc::SumMolecularEnergy**, and **sc::Volume**. ### virtual int sc::Function::value\_implemented () const` [virtual]` Information about the availability of values, gradients, and hessians. Reimplemented in **sc::SumMolecularEnergy**, **sc::TaylorMolecularEnergy**, **sc::CLKS**, **sc::HSOSKS**, **sc::UKS**, **sc::MBPT2**, **sc::MBPT2\_R12**, **sc::CLHF**, **sc::HSOSHF**, **sc::OSSHF**, **sc::TCHF**, **sc::UHF**, **sc::ExtendedHuckelWfn**, **sc::HCoreWfn**, and **sc::Shape**. ## Author Generated automatically by Doxygen for MPQC from the source code.