lines 6-84 of file: lib/python/cppad_py/hes_sparsity.py

# {xrst_begin py_hes_sparsity}
# {xrst_spell
#     bool
# }
# {xrst_comment_ch #}
#
#
# Hessian Sparsity Patterns
# #########################
#
# Syntax
# ******
#
# | *f*\ ``.for_hes_sparsity`` ( *select_domain* , *select_range* , *pattern_out* )
#
# *f*\ ``.rev_hes_sparsity`` ( *select_domain* , *select_range* , *pattern_out* )
#
# Purpose
# *******
# We use :math:`F : \B{R}^n \rightarrow \B{R}^m` to denote the
# function corresponding to the operation sequence stored in *f* .
# Fix a diagonal matrix :math:`D \in \B{R}^{n \times n}`, fix a vector
# :math:`r \in \B{R}^m`, and define
#
# .. math::
#
#    H(x) = D (r^\R{T} F)^{(2)} ( x ) D
#
# Given a sparsity pattern for :math:`D` and :math:`r`,
# these routines compute a sparsity pattern for :math:`H(x)`.
#
# x
# *
# Note that a sparsity pattern for :math:`H(x)` corresponds to the
# operation sequence stored in *f* and does not depend on
# the argument *x* .
#
# f
# *
# This object must have been returned by a previous call to the python
# :ref:`d_fun<py_fun_ctor-name>` constructor.
#
# select_domain
# *************
# The argument is a numpy vector with ``bool`` elements.
# It has size *n* and is a sparsity pattern for the diagonal of
# :math:`D`; i.e., *select_domain* [ *j* ] is true if and only if
# :math:`D_{j,j}` is possibly non-zero.
#
# select_range
# ************
# The argument is a numpy vector with ``bool`` elements.
# It has size *m* and is a sparsity pattern for the vector
# :math:`r`; i.e., *select_range* [ *i* ] is true if and only if
# :math:`r_i` is possibly non-zero.
#
# pattern_out
# ***********
# This argument must have be a :ref:`pattern<py_sparse_rc@pattern>`
# returned by the ``sparse_rc`` constructor.
# This input value of *pattern_out* does not matter.
# Upon return *pattern_out* is a sparsity pattern for
# :math:`H(x)`.
#
# Sparsity for Component Wise Hessian
# ***********************************
# Suppose that :math:`D` is the identity matrix,
# and only the *i*-th component of *r* is possibly non-zero.
# In this case, *pattern_out* is a sparsity pattern for
# :math:`F_i^{(2)} ( x )`.
#
# {xrst_toc_hidden
#  example/python/core/sparse_hes_pattern_xam.py
# }
# Example
# *******
# :ref:`python<sparse_hes_pattern_xam.py-name>`
#
# {xrst_end py_hes_sparsity}