This is a non-templated, runtime-polymorphic generic implementation of the linear classifier objective. More...

#include <generic_linear.h>

Inheritance diagram for dismec::objective::GenericLinearClassifier:

Public Member Functions
	GenericLinearClassifier (std::shared_ptr< const GenericFeatureMatrix > X, std::unique_ptr< Objective > regularizer)

Public Member Functions inherited from dismec::objective::LinearClassifierBase
	LinearClassifierBase (std::shared_ptr< const GenericFeatureMatrix > X)

long	num_instances () const noexcept

long	num_variables () const noexcept override

BinaryLabelVector &	get_label_ref ()

void	update_costs (real_t positive, real_t negative)

Public Member Functions inherited from dismec::objective::Objective
	Objective ()

virtual	~Objective () noexcept=default

real_t	value (const HashVector &location)
	Evaluate the objective at the given `location`. More...

void	diag_preconditioner (const HashVector &location, Eigen::Ref< DenseRealVector > target)
	Get precondition to be used in CG optimization. More...

void	project_to_line (const HashVector &location, const DenseRealVector &direction)
	creates a function g such that `g(a) = objective(location + a * direction)` Use `lookup_on_line()` to evaluate `g`. More...

void	gradient_at_zero (Eigen::Ref< DenseRealVector > target)
	Gets the gradient for location zero. More...

void	gradient (const HashVector &location, Eigen::Ref< DenseRealVector > target)
	Evaluate the gradient at `location`. More...

void	hessian_times_direction (const HashVector &location, const DenseRealVector &direction, Eigen::Ref< DenseRealVector > target)
	Calculates the product of the Hessian matrix at `location` with `direction`. More...

void	gradient_and_pre_conditioner (const HashVector &location, Eigen::Ref< DenseRealVector > gradient, Eigen::Ref< DenseRealVector > pre)
	Combines the calculation of gradient and pre-conditioner, which may be more efficient in some cases. More...

Public Member Functions inherited from dismec::stats::Tracked
	Tracked ()
	Default constructor, creates the internal `stats::StatisticsCollection`. More...

void	register_stat (const std::string &name, std::unique_ptr< Statistics > stat)
	Registers a tracker for the statistics `name`. More...

std::shared_ptr< StatisticsCollection >	get_stats () const
	Gets an ownership-sharing reference to the `StatisticsCollection`. More...

Private Member Functions
real_t	value_from_xTw (const DenseRealVector &xTw)

void	invalidate_labels () override


real_t	value_unchecked (const HashVector &location) override

real_t	lookup_on_line (real_t position) override
	Looks up the value of the objective on the line defined by the last call to `project_to_line()`. More...

void	gradient_unchecked (const HashVector &location, Eigen::Ref< DenseRealVector > target) override

void	gradient_at_zero_unchecked (Eigen::Ref< DenseRealVector > target) override

void	hessian_times_direction_unchecked (const HashVector &location, const DenseRealVector &direction, Eigen::Ref< DenseRealVector > target) override

void	diag_preconditioner_unchecked (const HashVector &location, Eigen::Ref< DenseRealVector > target) override

void	gradient_and_pre_conditioner_unchecked (const HashVector &location, Eigen::Ref< DenseRealVector > gradient, Eigen::Ref< DenseRealVector > pre) override

void	project_to_line_unchecked (const HashVector &location, const DenseRealVector &direction) override


virtual void	calculate_loss (const DenseRealVector &scores, const BinaryLabelVector &labels, DenseRealVector &out) const =0
	Calculates the loss for each instance. More...

virtual void	calculate_derivative (const DenseRealVector &scores, const BinaryLabelVector &labels, DenseRealVector &out) const =0
	Calculates the derivative of the loss with respect to the scores for each instance. More...

virtual void	calculate_2nd_derivative (const DenseRealVector &scores, const BinaryLabelVector &labels, DenseRealVector &out) const =0
	Calculates the 2nd derivative of the loss with respect to the scores for each instance. More...

const DenseRealVector &	cached_derivative (const HashVector &location)
	Gets the derivative vector for the current location. More...

const DenseRealVector &	cached_2nd_derivative (const HashVector &location)
	Gets the 2nd derivative vector for the current location. More...

Private Attributes
CacheHelper	m_SecondDerivativeBuffer
	Cached value of the last calculation of the loss derivative. Needs to be invalidated when the labels change. More...

CacheHelper	m_DerivativeBuffer
	Cached value of the last calculation of the 2nd derivative. Needs to be invalidated when the labels change. More...

DenseRealVector	m_GenericInBuffer

DenseRealVector	m_GenericOutBuffer

std::unique_ptr< Objective >	m_Regularizer
	Pointer to the regularizer. More...

Additional Inherited Members
Protected Member Functions inherited from dismec::objective::LinearClassifierBase
const DenseRealVector &	x_times_w (const HashVector &w)
	Calculates the vector of feature matrix times weights `w` More...

template<class Derived >
void	update_xtw_cache (const HashVector &new_weight, const Eigen::MatrixBase< Derived > &new_result)
	Updates the cached value for x_times_w. More...

void	project_linear_to_line (const HashVector &location, const DenseRealVector &direction)
	Prepares the cache variables for line projection. More...

auto	line_interpolation (real_t t) const

void	declare_vector_on_last_line (const HashVector &location, real_t t) override
	State that the given vector corresponds to a certain position on the line of the last line search. More...

const GenericFeatureMatrix &	generic_features () const

const DenseFeatures &	dense_features () const

const SparseFeatures &	sparse_features () const

const DenseRealVector &	costs () const

const BinaryLabelVector &	labels () const

Protected Member Functions inherited from dismec::stats::Tracked
	~Tracked ()
	Non-virtual destructor. Declared protected, so we don't accidentally try to do a polymorphic delete. More...

template<class T >
void	record (stat_id_t stat, T &&value)
	Record statistics. This function just forwards all its arguments to the internal `StatisticsCollection`. More...

void	declare_stat (stat_id_t index, StatisticMetaData meta)
	Declares a new statistics. This function just forwards all its arguments to the internal `StatisticsCollection`. More...

void	declare_tag (tag_id_t index, std::string name)
	Declares a new tag. This function just forwards all its arguments to the internal `StatisticsCollection`. More...

template<class... Args>
void	set_tag (tag_id_t tag, long value)
	Set value of tag. This function just forwards all its arguments to the internal `StatisticsCollection`. More...

template<class... Args>
auto	make_timer (stat_id_t id, Args... args)
	Creates a new `ScopeTimer` using `stats::record_scope_time`. More...

Detailed Description

This is a non-templated, runtime-polymorphic generic implementation of the linear classifier objective.

It is implemented by reducing the operations of an Objective to just three functions:

These functions operate by writing their result into a pre-allocated array, yielding loss and derivatives for each instance in the feature matrix. By processing these in bulk, we ensure that the indirect-call overhead due to the virtual function becomes negligible. However, the indirect call still means that the optimizer cannot fuse the operations across the call boundary, and the usage of the intermediate buffer increases the memory bandwidth requirements.

Definition at line 25 of file generic_linear.h.

Constructor & Destructor Documentation

◆ GenericLinearClassifier()

GenericLinearClassifier::GenericLinearClassifier	(	std::shared_ptr< const GenericFeatureMatrix >	X,
		std::unique_ptr< Objective >	regularizer
	)

Definition at line 140 of file generic_linear.cpp.

References dismec::stats::Tracked::declare_stat(), m_Regularizer, anonymous_namespace{generic_linear.cpp}::STAT_GRAD_SPARSITY, and THROW_EXCEPTION.

Member Function Documentation

◆ cached_2nd_derivative()

const DenseRealVector & GenericLinearClassifier::cached_2nd_derivative ( const HashVector & location )

private

Gets the 2nd derivative vector for the current location.

Multiple calls with the same location will reuse a cached result. If no result is available, the derivative is calculated using calculate_2nd_derivative().

See also: calculate_2nd_derivative, m_SecondDerivativeBuffer

Definition at line 128 of file generic_linear.cpp.

◆ cached_derivative()

const DenseRealVector & GenericLinearClassifier::cached_derivative ( const HashVector & location )

private

Gets the derivative vector for the current location.

Multiple calls with the same location will reuse a cached result. If no result is available, the derivative is calculated using calculate_derivative().

See also: calculate_derivative, m_DerivativeBuffer

Definition at line 115 of file generic_linear.cpp.

References anonymous_namespace{generic_linear.cpp}::STAT_GRAD_SPARSITY.

◆ calculate_2nd_derivative()

virtual void dismec::objective::GenericLinearClassifier::calculate_2nd_derivative	(	const DenseRealVector &	scores,
		const BinaryLabelVector &	labels,
		DenseRealVector &	out
	)		const

privatepure virtual

Calculates the 2nd derivative of the loss with respect to the scores for each instance.

Parameters

[in]	scores	The scores, i.e. the product weights times features, for each instance.
[in]	labels	The binary labels as a vector of plus and minus ones.
[out]	out	This vector will be filled with the instance-wise loss 2nd derivatives.

Implemented in dismec::objective::GenericMarginClassifier< MarginFunction >.

◆ calculate_derivative()

virtual void dismec::objective::GenericLinearClassifier::calculate_derivative	(	const DenseRealVector &	scores,
		const BinaryLabelVector &	labels,
		DenseRealVector &	out
	)		const

privatepure virtual

Calculates the derivative of the loss with respect to the scores for each instance.

Parameters

[in]	scores	The scores, i.e. the product weights times features, for each instance.
[in]	labels	The binary labels as a vector of plus and minus ones.
[out]	out	This vector will be filled with the instance-wise loss derivatives.

Implemented in dismec::objective::GenericMarginClassifier< MarginFunction >.

◆ calculate_loss()

virtual void dismec::objective::GenericLinearClassifier::calculate_loss	(	const DenseRealVector &	scores,
		const BinaryLabelVector &	labels,
		DenseRealVector &	out
	)		const

privatepure virtual

Calculates the loss for each instance.

Parameters

[in]	scores	The scores, i.e. the product weights times features, for each instance.
[in]	labels	The binary labels as a vector of plus and minus ones.
[out]	out	This vector will be filled with the instance-wise loss value.

Implemented in dismec::objective::GenericMarginClassifier< MarginFunction >.

◆ diag_preconditioner_unchecked()

void GenericLinearClassifier::diag_preconditioner_unchecked	(	const HashVector &	location,
		Eigen::Ref< DenseRealVector >	target
	)

overrideprivatevirtual

The function that does the actual computation. This is called in diag_preconditioner() after the arguments have been validated. The default implementation returns ones.

Reimplemented from dismec::objective::Objective.

Definition at line 102 of file generic_linear.cpp.

References dismec::types::visit().

◆ gradient_and_pre_conditioner_unchecked()

void GenericLinearClassifier::gradient_and_pre_conditioner_unchecked	(	const HashVector &	location,
		Eigen::Ref< DenseRealVector >	gradient,
		Eigen::Ref< DenseRealVector >	pre
	)

overrideprivatevirtual

The function that does the actual computation. This is called in gradient_and_pre_conditioner() after the arguments have been validated. The default implementation sucessively calls gradient() and diag_preconditioner().

Reimplemented from dismec::objective::Objective.

Definition at line 53 of file generic_linear.cpp.

References dismec::types::visit().

◆ gradient_at_zero_unchecked()

void GenericLinearClassifier::gradient_at_zero_unchecked ( Eigen::Ref< DenseRealVector > target )

overrideprivatevirtual

The function that does the actual computation. This is called in gradient_at_zero() after the argument has been validated. The default implementation is rather inefficient and creates a new temporary zero vector.

Reimplemented from dismec::objective::Objective.

Definition at line 87 of file generic_linear.cpp.

References dismec::types::visit().

◆ gradient_unchecked()

void GenericLinearClassifier::gradient_unchecked	(	const HashVector &	location,
		Eigen::Ref< DenseRealVector >	target
	)

overrideprivatevirtual

The function that does the actual gradient computation. This is called in gradient() after the arguments have been validated.

Implements dismec::objective::Objective.

Definition at line 74 of file generic_linear.cpp.

References dismec::types::visit().

◆ hessian_times_direction_unchecked()

void GenericLinearClassifier::hessian_times_direction_unchecked	(	const HashVector &	location,
		const DenseRealVector &	direction,
		Eigen::Ref< DenseRealVector >	target
	)

overrideprivatevirtual

The function that does the actual computation. This is called in hessian_times_direction() after the arguments have been validated.

Implements dismec::objective::Objective.

Definition at line 38 of file generic_linear.cpp.

References dismec::types::visit().

◆ invalidate_labels()

void GenericLinearClassifier::invalidate_labels ( )

overrideprivatevirtual

This function will be called whenever m_Y changes so that derived classes can invalidate their caches.

Implements dismec::objective::LinearClassifierBase.

Definition at line 135 of file generic_linear.cpp.

◆ lookup_on_line()

real_t GenericLinearClassifier::lookup_on_line ( real_t position )

overrideprivatevirtual

Looks up the value of the objective on the line defined by the last call to project_to_line().

Parameters

position The location where the objective is calculated.

Returns: The value of objective(location + position * direction), where location and direction are the vectors passed to the last call of project_to_line().

Attention: This function may use results cached project_to_line(), so it has to be called after a call to that function. A new call to project_to_line() will change the line which is evaluated.

Implements dismec::objective::Objective.

Definition at line 25 of file generic_linear.cpp.

References dismec::l2_reg_sq_hinge_detail::value_from_xTw().

◆ project_to_line_unchecked()

void GenericLinearClassifier::project_to_line_unchecked	(	const HashVector &	location,
		const DenseRealVector &	direction
	)

overrideprivatevirtual

The function that does the actual computation. This is called in project_to_line() after the arguments have been validated.

Implements dismec::objective::Objective.

Definition at line 153 of file generic_linear.cpp.

References m_Regularizer, and dismec::objective::LinearClassifierBase::project_linear_to_line().

◆ value_from_xTw()

real_t GenericLinearClassifier::value_from_xTw ( const DenseRealVector & xTw )

private

Definition at line 31 of file generic_linear.cpp.

◆ value_unchecked()

real_t GenericLinearClassifier::value_unchecked ( const HashVector & location )

overrideprivatevirtual

The function that does the actual value computation. This is called in value() after the argument has been validated.

Implements dismec::objective::Objective.

Definition at line 20 of file generic_linear.cpp.

References dismec::l2_reg_sq_hinge_detail::value_from_xTw().

Member Data Documentation

◆ m_DerivativeBuffer

CacheHelper dismec::objective::GenericLinearClassifier::m_DerivativeBuffer

private

Cached value of the last calculation of the 2nd derivative. Needs to be invalidated when the labels change.

Definition at line 103 of file generic_linear.h.

◆ m_GenericInBuffer

DenseRealVector dismec::objective::GenericLinearClassifier::m_GenericInBuffer

private

Definition at line 105 of file generic_linear.h.

◆ m_GenericOutBuffer

DenseRealVector dismec::objective::GenericLinearClassifier::m_GenericOutBuffer

private

Definition at line 106 of file generic_linear.h.

◆ m_Regularizer

std::unique_ptr<Objective> dismec::objective::GenericLinearClassifier::m_Regularizer

private

Pointer to the regularizer.

Definition at line 109 of file generic_linear.h.

Referenced by GenericLinearClassifier(), and project_to_line_unchecked().

◆ m_SecondDerivativeBuffer

CacheHelper dismec::objective::GenericLinearClassifier::m_SecondDerivativeBuffer

private

Cached value of the last calculation of the loss derivative. Needs to be invalidated when the labels change.

Definition at line 101 of file generic_linear.h.

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

src/objective/generic_linear.h
src/objective/generic_linear.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ GenericLinearClassifier()

Member Function Documentation

◆ cached_2nd_derivative()

◆ cached_derivative()

◆ calculate_2nd_derivative()

◆ calculate_derivative()

◆ calculate_loss()

◆ diag_preconditioner_unchecked()

◆ gradient_and_pre_conditioner_unchecked()

◆ gradient_at_zero_unchecked()

◆ gradient_unchecked()

◆ hessian_times_direction_unchecked()

◆ invalidate_labels()

◆ lookup_on_line()

◆ project_to_line_unchecked()

◆ value_from_xTw()

◆ value_unchecked()

Member Data Documentation

◆ m_DerivativeBuffer

◆ m_GenericInBuffer

◆ m_GenericOutBuffer

◆ m_Regularizer

◆ m_SecondDerivativeBuffer