Base class for controls that adjust a single scalar parameter (held in a postprocessor) once per fixed-point iteration so that a sub-application output postprocessor matches a target function of time. More...

#include <InversionControlBase.h>

Inheritance diagram for InversionControlBase:

[legend]

Classes
struct	IterationUpdate
	One iteration's update, produced by the derived scheme and applied by execute(). More...

Public Types
typedef DataFileName	DataFileParameterType

Public Member Functions
	InversionControlBase (const InputParameters &parameters)

virtual void	execute () override final
	Template method: reads the current (parameter, output) sample, delegates the scheme-specific decision to computeUpdate(), and applies it (publish, residual, next parameter).

std::vector< std::string > &	getDependencies ()

virtual bool	enabled () const

std::shared_ptr< MooseObject >	getSharedPtr ()

std::shared_ptr< const MooseObject >	getSharedPtr () const

bool	isKokkosObject () const

MooseApp &	getMooseApp () const

const std::string &	type () const

const std::string &	name () const

std::string	typeAndName () const

MooseObjectParameterName	uniqueParameterName (const std::string &parameter_name) const

MooseObjectName	uniqueName () const

const InputParameters &	parameters () const

const hit::Node *	getHitNode () const

bool	hasBase () const

const std::string &	getBase () const

const T &	getParam (const std::string &name) const

std::vector< std::pair< T1, T2 > >	getParam (const std::string &param1, const std::string &param2) const

const T *	queryParam (const std::string &name) const

const T &	getRenamedParam (const std::string &old_name, const std::string &new_name) const

T	getCheckedPointerParam (const std::string &name, const std::string &error_string="") const

bool	isParamValid (const std::string &name) const

bool	isParamSetByUser (const std::string &name) const

void	connectControllableParams (const std::string &parameter, const std::string &object_type, const std::string &object_name, const std::string &object_parameter) const

void	paramError (const std::string &param, Args... args) const

void	paramWarning (const std::string &param, Args... args) const

void	paramWarning (const std::string &param, Args... args) const

void	paramInfo (const std::string &param, Args... args) const

std::string	messagePrefix (const bool hit_prefix=true) const

std::string	errorPrefix (const std::string &) const

void	mooseError (Args &&... args) const

void	mooseDocumentedError (const std::string &repo_name, const unsigned int issue_num, Args &&... args) const

void	mooseErrorNonPrefixed (Args &&... args) const

void	mooseWarning (Args &&... args) const

void	mooseWarning (Args &&... args) const

void	mooseWarningNonPrefixed (Args &&... args) const

void	mooseWarningNonPrefixed (Args &&... args) const

void	mooseDeprecated (Args &&... args) const

void	mooseDeprecated (Args &&... args) const

void	mooseDeprecatedNoTrace (Args &&... args) const

void	mooseInfo (Args &&... args) const

void	callMooseError (std::string msg, const bool with_prefix, const hit::Node *node=nullptr, const bool show_trace=true) const

std::string	getDataFileName (const std::string &param) const

std::string	getDataFileNameByName (const std::string &relative_path) const

std::string	getDataFilePath (const std::string &relative_path) const

bool	isImplicit ()

Moose::StateArg	determineState () const

virtual void	initialSetup ()

virtual void	timestepSetup ()

virtual void	jacobianSetup ()

virtual void	residualSetup ()

virtual void	subdomainSetup ()

virtual void	customSetup (const ExecFlagType &)

const ExecFlagEnum &	getExecuteOnEnum () const

const Function &	getFunction (const std::string &name) const

const Function &	getFunctionByName (const FunctionName &name) const

bool	hasFunction (const std::string &param_name) const

bool	hasFunctionByName (const FunctionName &name) const

Moose::Kokkos::Function	getKokkosFunction (const std::string &name) const

const T &	getKokkosFunction (const std::string &name) const

Moose::Kokkos::Function	getKokkosFunctionByName (const FunctionName &name) const

const T &	getKokkosFunctionByName (const FunctionName &name) const

bool	hasKokkosFunction (const std::string &param_name) const

bool	hasKokkosFunctionByName (const FunctionName &name) const

UserObjectName	getUserObjectName (const std::string &param_name) const

const T &	getUserObject (const std::string &param_name, bool is_dependency=true) const

const T &	getUserObjectByName (const UserObjectName &object_name, bool is_dependency=true) const

const UserObjectBase &	getUserObjectBase (const std::string &param_name, bool is_dependency=true) const

const UserObjectBase &	getUserObjectBaseByName (const UserObjectName &object_name, bool is_dependency=true) const

bool	hasUserObject (const std::string &param_name) const

bool	hasUserObject (const std::string &param_name) const

bool	hasUserObject (const std::string &param_name) const

bool	hasUserObject (const std::string &param_name) const

bool	hasUserObjectByName (const UserObjectName &object_name) const

bool	hasUserObjectByName (const UserObjectName &object_name) const

bool	hasUserObjectByName (const UserObjectName &object_name) const

bool	hasUserObjectByName (const UserObjectName &object_name) const

PerfGraph &	perfGraph ()

bool	isDefaultPostprocessorValue (const std::string &param_name, const unsigned int index=0) const

bool	hasPostprocessor (const std::string &param_name, const unsigned int index=0) const

bool	hasPostprocessorByName (const PostprocessorName &name) const

std::size_t	coupledPostprocessors (const std::string &param_name) const

const PostprocessorName &	getPostprocessorName (const std::string &param_name, const unsigned int index=0) const

const VectorPostprocessorValue &	getVectorPostprocessorValue (const std::string &param_name, const std::string &vector_name) const

const VectorPostprocessorValue &	getVectorPostprocessorValue (const std::string &param_name, const std::string &vector_name, bool needs_broadcast) const

const VectorPostprocessorValue &	getVectorPostprocessorValueByName (const VectorPostprocessorName &name, const std::string &vector_name) const

const VectorPostprocessorValue &	getVectorPostprocessorValueByName (const VectorPostprocessorName &name, const std::string &vector_name, bool needs_broadcast) const

const VectorPostprocessorValue &	getVectorPostprocessorValueOld (const std::string &param_name, const std::string &vector_name) const

const VectorPostprocessorValue &	getVectorPostprocessorValueOld (const std::string &param_name, const std::string &vector_name, bool needs_broadcast) const

const VectorPostprocessorValue &	getVectorPostprocessorValueOldByName (const VectorPostprocessorName &name, const std::string &vector_name) const

const VectorPostprocessorValue &	getVectorPostprocessorValueOldByName (const VectorPostprocessorName &name, const std::string &vector_name, bool needs_broadcast) const

const ScatterVectorPostprocessorValue &	getScatterVectorPostprocessorValue (const std::string &param_name, const std::string &vector_name) const

const ScatterVectorPostprocessorValue &	getScatterVectorPostprocessorValueByName (const VectorPostprocessorName &name, const std::string &vector_name) const

const ScatterVectorPostprocessorValue &	getScatterVectorPostprocessorValueOld (const std::string &param_name, const std::string &vector_name) const

const ScatterVectorPostprocessorValue &	getScatterVectorPostprocessorValueOldByName (const VectorPostprocessorName &name, const std::string &vector_name) const

bool	hasVectorPostprocessor (const std::string &param_name, const std::string &vector_name) const

bool	hasVectorPostprocessor (const std::string &param_name) const

bool	hasVectorPostprocessorByName (const VectorPostprocessorName &name, const std::string &vector_name) const

bool	hasVectorPostprocessorByName (const VectorPostprocessorName &name) const

const VectorPostprocessorName &	getVectorPostprocessorName (const std::string &param_name) const

const PostprocessorValue &	getPostprocessorValue (const std::string &param_name, const unsigned int index=0) const

const PostprocessorValue &	getPostprocessorValue (const std::string &param_name, const unsigned int index=0) const

const PostprocessorValue &	getPostprocessorValueOld (const std::string &param_name, const unsigned int index=0) const

const PostprocessorValue &	getPostprocessorValueOld (const std::string &param_name, const unsigned int index=0) const

const PostprocessorValue &	getPostprocessorValueOlder (const std::string &param_name, const unsigned int index=0) const

const PostprocessorValue &	getPostprocessorValueOlder (const std::string &param_name, const unsigned int index=0) const

virtual const PostprocessorValue &	getPostprocessorValueByName (const PostprocessorName &name) const

virtual const PostprocessorValue &	getPostprocessorValueByName (const PostprocessorName &name) const

const PostprocessorValue &	getPostprocessorValueOldByName (const PostprocessorName &name) const

const PostprocessorValue &	getPostprocessorValueOldByName (const PostprocessorName &name) const

const PostprocessorValue &	getPostprocessorValueOlderByName (const PostprocessorName &name) const

const PostprocessorValue &	getPostprocessorValueOlderByName (const PostprocessorName &name) const

bool	isVectorPostprocessorDistributed (const std::string &param_name) const

bool	isVectorPostprocessorDistributed (const std::string &param_name) const

bool	isVectorPostprocessorDistributedByName (const VectorPostprocessorName &name) const

bool	isVectorPostprocessorDistributedByName (const VectorPostprocessorName &name) const

const Parallel::Communicator &	comm () const

processor_id_type	n_processors () const

processor_id_type	processor_id () const

Static Public Member Functions
static InputParameters	validParams ()

static void	callMooseError (MooseApp const app, const InputParameters &params, std::string msg, const bool with_prefix, const hit::Node node, const bool show_trace=true)

static MultiMooseEnum	getExecuteOptions ()

Public Attributes
	usingCombinedWarningSolutionWarnings

const ConsoleStream	_console

Static Public Attributes
static const std::string	type_param

static const std::string	name_param

static const std::string	unique_name_param

static const std::string	app_param

static const std::string	moose_base_param

static const std::string	kokkos_object_param

Protected Member Functions
virtual IterationUpdate	computeUpdate (unsigned int it, Real p_used, Real y, Real y_target)=0
	Compute this iteration's update from the current sample: the 1-based fixed-point iteration `it` and the (parameter, output) pair (`p_used`, `y`) that produced it, against target `y_target`.

unsigned int	fixedPointIteration () const
	1-based fixed-point iteration (1 on the first iteration of each fixed-point solve, including restep)

Real	targetValue () const
	Target output value at the current time.

void	publishConvergedParameter (Real p)
	Publish a parameter value to the optional converged-parameter postprocessor (no-op if unset)

void	setParameter (Real p)
	Write the next parameter guess to the parameter postprocessor.

Real	linearRootUpdate (Real p_a, Real y_a, Real p_b, Real y_b, Real y_target)
	One guarded linear-model root update from two (parameter, output) samples – a secant step shared by the secant and finite-difference Newton schemes: returns `p_b` - (y_b - y_target) * (p_b - p_a) / (y_b - y_a).

Real	normalizedResidual (Real y) const
	Normalized convergence residual for output value `y:` \|y - targetValue()\| / max(absolute_tolerance, relative_tolerance*\|targetValue()\|).

void	setResidual (Real value)
	Write a value to the residual postprocessor that the Convergence object compares against 1.

bool	hasControllableParameterByName (const std::string &name) const

void	flagInvalidSolutionInternal (const InvalidSolutionID invalid_solution_id) const

InvalidSolutionID	registerInvalidSolutionInternal (const std::string &message, const bool warning) const

PerfID	registerTimedSection (const std::string &section_name, const unsigned int level) const

PerfID	registerTimedSection (const std::string &section_name, const unsigned int level, const std::string &live_message, const bool print_dots=true) const

std::string	timedSectionName (const std::string &section_name) const

virtual void	addUserObjectDependencyHelper (const UserObjectBase &) const

T &	declareRestartableData (const std::string &data_name, Args &&... args)

ManagedValue< T >	declareManagedRestartableDataWithContext (const std::string &data_name, void *context, Args &&... args)

const T &	getRestartableData (const std::string &data_name) const

T &	declareRestartableDataWithContext (const std::string &data_name, void *context, Args &&... args)

T &	declareRecoverableData (const std::string &data_name, Args &&... args)

T &	declareRestartableDataWithObjectName (const std::string &data_name, const std::string &object_name, Args &&... args)

T &	declareRestartableDataWithObjectNameWithContext (const std::string &data_name, const std::string &object_name, void *context, Args &&... args)

std::string	restartableName (const std::string &data_name) const

virtual void	addPostprocessorDependencyHelper (const PostprocessorName &) const

virtual void	addVectorPostprocessorDependencyHelper (const VectorPostprocessorName &) const

const ReporterContextBase &	getReporterContextBaseByName (const ReporterName &reporter_name) const

const ReporterName &	getReporterName (const std::string &param_name) const

virtual void	addReporterDependencyHelper (const ReporterName &)

ControllableParameter	getControllableParameter (const std::string &param_name)

ControllableParameter	getControllableParameter (const std::string &param_name)

ControllableParameter	getControllableParameterByName (const std::string &param_name)

ControllableParameter	getControllableParameterByName (const std::string &tag, const std::string &object_name, const std::string &param_name)

ControllableParameter	getControllableParameterByName (const MooseObjectName &object_name, const std::string &param_name)

ControllableParameter	getControllableParameterByName (const MooseObjectParameterName &param_name)

ControllableParameter	getControllableParameterByName (const std::string &param_name)

ControllableParameter	getControllableParameterByName (const std::string &tag, const std::string &object_name, const std::string &param_name)

ControllableParameter	getControllableParameterByName (const MooseObjectName &object_name, const std::string &param_name)

ControllableParameter	getControllableParameterByName (const MooseObjectParameterName &param_name)

T	getControllableValue (const std::string &name, bool warn_when_values_differ=true)

T	getControllableValue (const std::string &name, bool warn_when_values_differ=true)

T	getControllableValueByName (const std::string &name, bool warn_when_values_differ=true)

T	getControllableValueByName (const std::string &object_name, const std::string &param_name, bool warn_when_values_differ=true)

T	getControllableValueByName (const MooseObjectName &object_name, const std::string &param_name, bool warn_when_values_differ=true)

T	getControllableValueByName (const std::string &tag, const std::string &object_name, const std::string &param_name, bool warn_when_values_differ=true)

T	getControllableValueByName (const MooseObjectParameterName &desired, bool warn_when_values_differ=true)

T	getControllableValueByName (const std::string &name, bool warn_when_values_differ=true)

T	getControllableValueByName (const std::string &object_name, const std::string &param_name, bool warn_when_values_differ=true)

T	getControllableValueByName (const MooseObjectName &object_name, const std::string &param_name, bool warn_when_values_differ=true)

T	getControllableValueByName (const std::string &tag, const std::string &object_name, const std::string &param_name, bool warn_when_values_differ=true)

T	getControllableValueByName (const MooseObjectParameterName &desired, bool warn_when_values_differ=true)

void	setControllableValue (const std::string &name, const T &value)

void	setControllableValue (const std::string &name, const T &value)

void	setControllableValueByName (const std::string &name, const T &value)

void	setControllableValueByName (const std::string &object_name, const std::string &param_name, const T &value)

void	setControllableValueByName (const MooseObjectName &object_name, const std::string &param_name, const T &value)

void	setControllableValueByName (const std::string &tag, const std::string &object_name, const std::string &param_name, const T &value)

void	setControllableValueByName (const MooseObjectParameterName &name, const T &value)

void	setControllableValueByName (const std::string &name, const T &value)

void	setControllableValueByName (const std::string &object_name, const std::string &param_name, const T &value)

void	setControllableValueByName (const MooseObjectName &object_name, const std::string &param_name, const T &value)

void	setControllableValueByName (const std::string &tag, const std::string &object_name, const std::string &param_name, const T &value)

void	setControllableValueByName (const MooseObjectParameterName &name, const T &value)

const T &	getReporterValue (const std::string &param_name, const std::size_t time_index=0)

const T &	getReporterValue (const std::string &param_name, ReporterMode mode, const std::size_t time_index=0)

const T &	getReporterValue (const std::string &param_name, const std::size_t time_index=0)

const T &	getReporterValue (const std::string &param_name, ReporterMode mode, const std::size_t time_index=0)

const T &	getReporterValueByName (const ReporterName &reporter_name, const std::size_t time_index=0)

const T &	getReporterValueByName (const ReporterName &reporter_name, ReporterMode mode, const std::size_t time_index=0)

const T &	getReporterValueByName (const ReporterName &reporter_name, const std::size_t time_index=0)

const T &	getReporterValueByName (const ReporterName &reporter_name, ReporterMode mode, const std::size_t time_index=0)

bool	hasReporterValue (const std::string &param_name) const

bool	hasReporterValue (const std::string &param_name) const

bool	hasReporterValue (const std::string &param_name) const

bool	hasReporterValue (const std::string &param_name) const

bool	hasReporterValueByName (const ReporterName &reporter_name) const

bool	hasReporterValueByName (const ReporterName &reporter_name) const

bool	hasReporterValueByName (const ReporterName &reporter_name) const

bool	hasReporterValueByName (const ReporterName &reporter_name) const

Protected Attributes
const PostprocessorValue &	_output
	Sub-app output value transferred back to the main app (compared against the target)

const PostprocessorValue &	_param
	Parameter value consumed by the most recent sub-app solve (read in place)

const PostprocessorName	_param_name
	Name of the parameter postprocessor to update with the next guess.

const std::optional< PostprocessorName >	_converged_param_name
	Optional postprocessor to publish the parameter value that produced the current output.

const Function &	_target_function
	Target output as a function of time.

const PostprocessorName	_residual_name
	Name of the postprocessor the control writes with the normalized convergence residual.

const Real	_abs_tol
	Absolute tolerance on \|output - target\|.

const Real	_rel_tol
	Relative tolerance on \|output - target\|, relative to \|target\|.

FEProblemBase &	_fe_problem

std::vector< std::string >	_depends_on

const bool &	_enabled

MooseApp &	_app

Factory &	_factory

ActionFactory &	_action_factory

const std::string &	_type

const std::string &	_name

const InputParameters &	_pars

MooseApp &	_pg_moose_app

const std::string	_prefix

const InputParameters &	_ti_params

FEProblemBase &	_ti_feproblem

bool	_is_implicit

Real &	_t

const Real &	_t_old

int &	_t_step

Real &	_dt

Real &	_dt_old

bool	_is_transient

const ExecFlagEnum &	_execute_enum

const ExecFlagType &	_current_execute_flag

MooseApp &	_restartable_app

const std::string	_restartable_system_name

const THREAD_ID	_restartable_tid

const bool	_restartable_read_only

const Parallel::Communicator &	_communicator

Private Member Functions
const Moose::FunctionBase *	getKokkosFunctionByNameHelper (const FunctionName &name) const

const UserObjectBase &	getUserObjectFromFEProblem (const UserObjectName &object_name, const THREAD_ID tid=0) const

const T &	castUserObject (const UserObjectBase &uo_base, const std::string &param_name="") const

void	mooseObjectError (const std::string &param_name, std::stringstream &oss) const

const std::string &	userObjectType (const UserObjectBase &uo) const

const std::string &	userObjectName (const UserObjectBase &uo) const

RestartableDataValue &	registerRestartableDataOnApp (std::unique_ptr< RestartableDataValue > data, THREAD_ID tid) const

void	registerRestartableNameWithFilterOnApp (const std::string &name, Moose::RESTARTABLE_FILTER filter)

RestartableData< T > &	declareRestartableDataHelper (const std::string &data_name, void *context, Args &&... args) const

const PostprocessorName &	getPostprocessorNameInternal (const std::string &param_name, const unsigned int index, const bool allow_default_value=true) const

bool	isDefaultPostprocessorValueByName (const PostprocessorName &name) const

PostprocessorValue	getDefaultPostprocessorValueByName (const PostprocessorName &name) const

void	checkParam (const std::string &param_name, const unsigned int index=std::numeric_limits< unsigned int >::max()) const

bool	postprocessorsAdded () const

const VectorPostprocessorValue &	getVectorPostprocessorByNameHelper (const VectorPostprocessorName &name, const std::string &vector_name, bool broadcast, std::size_t t_index) const

const VectorPostprocessorContext< VectorPostprocessorValue > &	getVectorPostprocessorContextByNameHelper (const VectorPostprocessorName &name, const std::string &vector_name) const

bool	vectorPostprocessorsAdded () const

bool	reportersAdded () const

void	possiblyCheckHasReporter (const ReporterName &reporter_name, const std::string &param_name="") const

const PostprocessorValue &	getPostprocessorValueInternal (const std::string &param_name, unsigned int index, std::size_t t_index) const

const PostprocessorValue &	getPostprocessorValueInternal (const std::string &param_name, unsigned int index, std::size_t t_index) const

const PostprocessorValue &	getPostprocessorValueByNameInternal (const PostprocessorName &name, std::size_t t_index) const

const PostprocessorValue &	getPostprocessorValueByNameInternal (const PostprocessorName &name, std::size_t t_index) const

void	possiblyCheckHasVectorPostprocessor (const std::string &param_name, const std::string &vector_name) const

void	possiblyCheckHasVectorPostprocessor (const std::string &param_name, const std::string &vector_name) const

void	possiblyCheckHasVectorPostprocessorByName (const VectorPostprocessorName &name, const std::string &vector_name) const

void	possiblyCheckHasVectorPostprocessorByName (const VectorPostprocessorName &name, const std::string &vector_name) const

Static Private Member Functions
static const hit::Node *	getHitNode (const InputParameters &params)

static std::string	messagePrefix (const InputParameters &params, const bool hit_prefix)

Private Attributes
InputParameterWarehouse &	_input_parameter_warehouse

const ParallelParamObject &	_parent

const MooseBase &	_si_moose_base

const FEProblemBase *	_si_problem

const std::string	_ti_name

ExecFlagEnum	_empty_execute_enum

const MooseObject &	_fni_object

const InputParameters &	_fni_params

FEProblemBase &	_fni_feproblem

const THREAD_ID	_fni_tid

const MooseObject &	_uoi_moose_object

const FEProblemBase &	_uoi_feproblem

const THREAD_ID	_uoi_tid

const RestartableDataMapName	_metaname

std::string	_restartable_name

const MooseObject &	_ppi_moose_object

const InputParameters &	_ppi_params

const FEProblemBase &	_ppi_feproblem

std::map< PostprocessorName, std::unique_ptr< PostprocessorValue > >	_default_values

const bool	_broadcast_by_default

const MooseObject &	_vpi_moose_object

const FEProblemBase &	_vpi_feproblem

const THREAD_ID	_vpi_tid

const InputParameters &	_ri_params

FEProblemBase &	_ri_fe_problem_base

const ReporterData &	_ri_reporter_data

const MooseObject &	_ri_moose_object

Detailed Description

Base class for controls that adjust a single scalar parameter (held in a postprocessor) once per fixed-point iteration so that a sub-application output postprocessor matches a target function of time.

It factors the shared plumbing (parameter/output postprocessors, target function, and optional publishing of the converged parameter) and the guarded secant update; derived classes implement computeUpdate() with their specific iteration scheme. The outer iteration, convergence, and time-step cutting are owned by the executioner and the Convergence system.

Definition at line 26 of file InversionControlBase.h.

Constructor & Destructor Documentation

◆ InversionControlBase()

InversionControlBase::InversionControlBase ( const InputParameters & parameters )

Definition at line 59 of file InversionControlBase.C.

  : Control(parameters),
    _output(getPostprocessorValue("output_postprocessor")),
    _param(getPostprocessorValue("parameter_postprocessor")),
    _param_name(getParam<PostprocessorName>("parameter_postprocessor")),
    _converged_param_name(
        isParamValid("converged_parameter_postprocessor")
            ? std::make_optional(getParam<PostprocessorName>("converged_parameter_postprocessor"))
            : std::nullopt),
    _target_function(getFunction("target_function")),
    _residual_name(getParam<PostprocessorName>("residual_postprocessor")),
    _abs_tol(getParam<Real>("absolute_tolerance")),
    _rel_tol(getParam<Real>("relative_tolerance"))
{
}

Member Function Documentation

◆ computeUpdate()

virtual IterationUpdate InversionControlBase::computeUpdate	(	unsigned int	it,
		Real	p_used,
		Real	y,
		Real	y_target
	)

protectedpure virtual

Compute this iteration's update from the current sample: the 1-based fixed-point iteration it and the (parameter, output) pair (p_used, y) that produced it, against target y_target.

Implemented in NewtonInversionControl, and SecantInversionControl.

Referenced by execute().

◆ execute()

void InversionControlBase::execute ( )

finaloverridevirtual

Template method: reads the current (parameter, output) sample, delegates the scheme-specific decision to computeUpdate(), and applies it (publish, residual, next parameter).

Derived classes implement computeUpdate(), not this.

Implements Control.

Definition at line 102 of file InversionControlBase.C.

{
  const unsigned int it = fixedPointIteration();
  const Real p_used = _param;
  const Real y = _output;
  const Real y_target = targetValue();
 
  const IterationUpdate update = computeUpdate(it, p_used, y, y_target);
 
  // Publish the parameter that produced the current output (the solution at convergence).
  if (update.publish)
    publishConvergedParameter(p_used);
  // Report the convergence residual the fixed-point Convergence object compares against 1.
  setResidual(update.residual);
  // Write the next guess back to the working parameter postprocessor.
  setParameter(update.next_parameter);
}

◆ fixedPointIteration()

unsigned int InversionControlBase::fixedPointIteration ( ) const

protected

1-based fixed-point iteration (1 on the first iteration of each fixed-point solve, including restep)

Definition at line 76 of file InversionControlBase.C.

{
  Executioner * const executioner = _app.getExecutioner();
  // hasSolveObject<FixedPointSolve>() guards the null (executor-style executioners never build
  // one); hasFixedPointIteration() then checks that fixed-point iteration is actually enabled.
  // Without the second check a standard executioner with no fixed-point settings still owns a
  // FixedPointSolve, so the control would silently drift the parameter once per time step instead
  // of iterating.
  if (!executioner || !executioner->hasSolveObject<FixedPointSolve>() ||
      !executioner->fixedPointSolve().hasFixedPointIteration())
    mooseError(
        "requires an executioner configured to perform fixed-point (MultiApp) iterations; set "
        "'fixed_point_max_its' greater than 1 (or otherwise enable fixed-point iteration) on "
        "the executioner.");
  // numFixedPointIts() returns _fixed_point_it + 1, i.e. 1 on the first iteration of each fresh
  // fixed-point solve (including a restep retry).
  return executioner->fixedPointSolve().numFixedPointIts();
}

Referenced by execute().

◆ linearRootUpdate()

Real InversionControlBase::linearRootUpdate	(	Real	p_a,
		Real	y_a,
		Real	p_b,
		Real	y_b,
		Real	y_target
	)

protected

One guarded linear-model root update from two (parameter, output) samples – a secant step shared by the secant and finite-difference Newton schemes: returns p_b - (y_b - y_target) * (p_b - p_a) / (y_b - y_a).

If the denominator or slope is too small to divide by, emits a warning and returns p_b unchanged.

Definition at line 134 of file InversionControlBase.C.

{
  const Real dp = p_b - p_a;
  const Real dy = y_b - y_a;
  // Guard a vanishing or non-finite denominator/slope before dividing. The magnitude-scaled
  // threshold is a pragmatic "dy too small" heuristic, not a principled relative tolerance; the
  // finiteness check also traps a NaN/Inf sample from a diverging forward solve, which the "<"
  // comparisons alone would let through (every comparison with NaN is false).
  if (!std::isfinite(dp) || !std::isfinite(dy) || std::abs(dp) < 1e-15 ||
      std::abs(dy) < 1e-15 * (std::abs(y_b) + std::abs(y_a) + 1.0))
  {
    mooseWarning("The parameter update at t = ",
                 _t,
                 " has a vanishing or non-finite denominator or slope; leaving the parameter "
                 "unchanged.");
    return p_b;
  }
  return p_b - (y_b - y_target) * dp / dy;
}

Referenced by NewtonInversionControl::computeUpdate(), and SecantInversionControl::computeUpdate().

◆ normalizedResidual()

Real InversionControlBase::normalizedResidual ( Real y ) const

protected

Normalized convergence residual for output value y: |y - targetValue()| / max(absolute_tolerance, relative_tolerance*|targetValue()|).

A value <= 1 means the absolute OR relative criterion is satisfied. The denominator is always positive because absolute_tolerance is range-checked > 0, so no divide guard is needed. When targetValue() is 0 the relative term vanishes and the criterion collapses to the purely absolute test |y| <= absolute_tolerance; choose absolute_tolerance accordingly for targets that cross or sit at zero, where a relative tolerance carries no meaning.

Definition at line 155 of file InversionControlBase.C.

{
  const Real target = targetValue();
  return std::abs(y - target) / std::max(_abs_tol, _rel_tol * std::abs(target));
}

Referenced by NewtonInversionControl::computeUpdate(), and SecantInversionControl::computeUpdate().

◆ publishConvergedParameter()

void InversionControlBase::publishConvergedParameter ( Real p )

protected

Publish a parameter value to the optional converged-parameter postprocessor (no-op if unset)

Definition at line 121 of file InversionControlBase.C.

{
  if (_converged_param_name)
    _fe_problem.setPostprocessorValueByName(*_converged_param_name, p);
}

Referenced by execute().

◆ setParameter()

void InversionControlBase::setParameter ( Real p )

protected

Write the next parameter guess to the parameter postprocessor.

Definition at line 128 of file InversionControlBase.C.

{
  _fe_problem.setPostprocessorValueByName(_param_name, p);
}

Referenced by execute().

◆ setResidual()

void InversionControlBase::setResidual ( Real value )

protected

Write a value to the residual postprocessor that the Convergence object compares against 1.

Definition at line 162 of file InversionControlBase.C.

{
  _fe_problem.setPostprocessorValueByName(_residual_name, value);
}

Referenced by execute().

◆ targetValue()

Real InversionControlBase::targetValue ( ) const

protected

Target output value at the current time.

Definition at line 96 of file InversionControlBase.C.

{
  return _target_function.value(_t);
}

Referenced by execute(), and normalizedResidual().

◆ validParams()

InputParameters InversionControlBase::validParams ( )

static

Definition at line 22 of file InversionControlBase.C.

{
  InputParameters params = Control::validParams();
 
  params.addRequiredParam<PostprocessorName>(
      "output_postprocessor",
      "Postprocessor holding the sub-app output to compare against the target.");
  params.addRequiredParam<PostprocessorName>(
      "parameter_postprocessor",
      "Postprocessor (e.g. a Receiver) holding the parameter value; read and updated in place.");
  params.addParam<PostprocessorName>(
      "converged_parameter_postprocessor",
      "Optional postprocessor to which the parameter value that produced the current output is "
      "written each iteration; at convergence this holds the inverse-problem solution.");
  params.addRequiredParam<FunctionName>(
      "target_function", "Function f(t) giving the target output value at each time step.");
  params.addRequiredParam<PostprocessorName>(
      "residual_postprocessor",
      "Postprocessor (e.g. a Receiver) the control writes with the normalized convergence "
      "residual; "
      "point the fixed-point Convergence object at it with a tolerance of 1.");
  params.addRangeCheckedParam<Real>("absolute_tolerance",
                                    1e-8,
                                    "absolute_tolerance>0",
                                    "Absolute tolerance on |output - target|.");
  params.addRangeCheckedParam<Real>(
      "relative_tolerance",
      1e-6,
      "relative_tolerance>0",
      "Relative tolerance on |output - target|, taken relative to |target|.");
 
  // Run once per fixed-point iteration, after the sub-app has solved and its output transferred.
  params.set<ExecFlagEnum>("execute_on") = EXEC_TIMESTEP_BEGIN;
 
  return params;
}

Referenced by NewtonInversionControl::validParams(), and SecantInversionControl::validParams().

Member Data Documentation

◆ _abs_tol

const Real InversionControlBase::_abs_tol

protected

Absolute tolerance on |output - target|.

Definition at line 106 of file InversionControlBase.h.

Referenced by normalizedResidual().

◆ _converged_param_name

const std::optional<PostprocessorName> InversionControlBase::_converged_param_name

protected

Optional postprocessor to publish the parameter value that produced the current output.

Definition at line 100 of file InversionControlBase.h.

Referenced by publishConvergedParameter().

◆ _output

const PostprocessorValue& InversionControlBase::_output

protected

Sub-app output value transferred back to the main app (compared against the target)

Definition at line 94 of file InversionControlBase.h.

Referenced by execute().

◆ _param

const PostprocessorValue& InversionControlBase::_param

protected

Parameter value consumed by the most recent sub-app solve (read in place)

Definition at line 96 of file InversionControlBase.h.

Referenced by execute().

◆ _param_name

const PostprocessorName InversionControlBase::_param_name

protected

Name of the parameter postprocessor to update with the next guess.

Definition at line 98 of file InversionControlBase.h.

Referenced by NewtonInversionControl::computeUpdate(), and setParameter().

◆ _rel_tol

const Real InversionControlBase::_rel_tol

protected

Relative tolerance on |output - target|, relative to |target|.

Definition at line 108 of file InversionControlBase.h.

Referenced by normalizedResidual().

◆ _residual_name

const PostprocessorName InversionControlBase::_residual_name

protected

Name of the postprocessor the control writes with the normalized convergence residual.

Definition at line 104 of file InversionControlBase.h.

Referenced by setResidual().

◆ _target_function

const Function& InversionControlBase::_target_function

protected

Target output as a function of time.

Definition at line 102 of file InversionControlBase.h.

Referenced by targetValue().

The documentation for this class was generated from the following files:

optimization/include/controls/InversionControlBase.h
optimization/src/controls/InversionControlBase.C

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ InversionControlBase()

Member Function Documentation

◆ computeUpdate()

◆ execute()

◆ fixedPointIteration()

◆ linearRootUpdate()

◆ normalizedResidual()

◆ publishConvergedParameter()

◆ setParameter()

◆ setResidual()

◆ targetValue()

◆ validParams()

Member Data Documentation

◆ _abs_tol

◆ _converged_param_name

◆ _output

◆ _param

◆ _param_name

◆ _rel_tol

◆ _residual_name

◆ _target_function