util::SampledFunction< XType, YType > Class Template Reference

Precomputed discrete sampling of a given function. More...

#include <SampledFunction.h>

Classes
struct	Range_t
	Record used during initialization. More...

Public Types
using	X_t = XType
	Type of value accepted by the function. More...
using	Y_t = YType
	Type of value returned by the function. More...
using	Function_t = std::function< Y_t(X_t)>
	Type of sampled function. More...
using	SubsampleData_t = gsl::span< Y_t const >
	Span of subsample data. Can be forward iterated. More...

Public Member Functions
	SampledFunction ()=default
template<typename Func >
	SampledFunction (Func const &function, X_t lower, X_t upper, gsl::index nSamples, gsl::index subsamples=1)
	Constructor: samples function in the specified range. More...
template<typename Stream >
void	dump (Stream &&out, std::string const &indent, std::string const &firstIndent) const
	Dumps the full content of the sampling into out stream. More...
template<typename Stream >
void	dump (Stream &&out, std::string const &indent="") const
	Dumps the full content of the sampling into out stream. More...
template<typename UntilFunc >
auto	extendRange (Function_t const &function, X_t lower, X_t min_upper, X_t step, UntilFunc &&until) -> Range_t
template<typename Func , typename UntilFunc >
	SampledFunction (Func const &function, X_t lower, X_t step, UntilFunc &&until, gsl::index subsamples, X_t min_upper)
	Constructor: samples function in the specified range. More...
template<typename Func , typename UntilFunc >
	SampledFunction (Func const &function, X_t lower, X_t step, UntilFunc &&until, gsl::index subsamples=1)
Query
gsl::index	size () const
	Returns the number of samples (in each subsample). More...
gsl::index	nSubsamples () const
	Returns the number of subsamples. More...
X_t	lower () const
	Returns the lower limit of the covered range. More...
X_t	upper () const
	Returns the upper limit of the covered range. More...
X_t	rangeSize () const
	Returns the extension of the covered range. More...
X_t	stepSize () const
	Returns the extension of a step. More...
X_t	substepSize () const
	Returns the base offset of the subsamples. More...
Access to the sampled data
Y_t	value (gsl::index iSample, gsl::index n=0U) const
	Returns the iSample value of the subsample with the specified index n. More...
SubsampleData_t	subsample (gsl::index const n) const
	Returns the data of the subsample with the specified index n. More...
gsl::index	stepIndex (X_t const x, gsl::index const iSubsample) const
	Returns the index of the step including x. More...
bool	isValidStepIndex (gsl::index const index) const
	Returns whether the specified step index is valid. More...
gsl::index	closestSubsampleIndex (X_t x) const
	Returns the subsample closest to the value x. More...

Static Public Attributes
static constexpr auto	npos = std::numeric_limits<gsl::index>::max()
	Invalid index of sample, returned in case of error. More...

Private Member Functions
	SampledFunction (Function_t const &function, Range_t const &range, gsl::index subsamples)
	Constructor implementation. More...
X_t	subsampleOffset (gsl::index n) const
	Returns the starting point of the subsample n. More...
std::size_t	computeTotalSize () const
	Computes the total size of the data. More...
void	fillSamples (Function_t const &function)
	Samples the function and fills the internal caches. More...
Y_t const *	subsampleData (gsl::index n) const
	Start of the block of values for subsample n (unchecked). More...
Y_t *	subsampleData (gsl::index n)

Static Private Member Functions
template<typename UntilFunc >
static Range_t	extendRange (Function_t const &function, X_t lower, X_t min_upper, X_t step, UntilFunc &&until)
template<typename T >
static T	wrapUp (T value, T range)
	Returns value made non-negative by adding multiples of range. More...

Private Attributes
X_t	fLower
	Lower limit of sampled range. More...
X_t	fUpper
	Upper limit of sampled range. More...
gsl::index	fNSamples
	Number of samples in the range. More...
gsl::index	fNSubsamples
	Number of subsamples. More...
X_t	fStep
	Step size. More...
std::vector< Y_t >	fAllSamples
	All samples, the entire first subsample first. More...

Detailed Description

template<typename XType, typename YType>
class util::SampledFunction< XType, YType >

Precomputed discrete sampling of a given function.

Template Parameters

XType	(default: double) type of value accepted by the function
YType	(default: as XType) type of value returned by the function

This object contains the sampling of a specified function at regular values of its variable.

If the size() of the sampling is requested to be N, there will be a sampling of N values covering the specified range in steps of the same length, last value excluded. The sampling happens at the beginning of each step.

In addition, subsampling can be requested. If M subsamples are requested, the first step is split in M points and from each one a sampling of N steps is started, causing overall M N samples to be computed.

Requirements

The function must be unary.

Technical note

The M subsamples are stored each one contiguously. Therefore a function with M subsamples of size N is different, at least in storage, from a function with a single sampling (no subsamples) of size M N.

Note

Due to the implementation of gsl::span, its iterators are valid only while the span object is valid as well. This means that a construct like: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} for (auto it = sf.subsample(0).begin(); it != sf.subsample(0).end(); ++it) // ... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ will mysteriously fail at run time because it refers to a temporary span that quickly falls out of scope (and the end iterator refers to a different span object, too). The correct pattern is to store the subsample result before iterating through it: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} auto const& subsample = sf.subsample(0); for (auto it = subsample.begin(); it != subsample.end(); ++it) // ... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ or, if appliable, let the range-for loop di that for us: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} for (auto value: sf.subsample(0)) // ... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This will not be the case any more with std::span, which apparently is going to satisfy the borrowed_range requirement.

Definition at line 31 of file SampledFunction.h.

Member Typedef Documentation

template<typename XType, typename YType>

using util::SampledFunction< XType, YType >::Function_t = std::function<Y_t(X_t)>

Type of sampled function.

Definition at line 97 of file SampledFunction.h.

template<typename XType, typename YType>

using util::SampledFunction< XType, YType >::SubsampleData_t = gsl::span<Y_t const>

Span of subsample data. Can be forward iterated.

Definition at line 103 of file SampledFunction.h.

template<typename XType, typename YType>

using util::SampledFunction< XType, YType >::X_t = XType

Type of value accepted by the function.

Definition at line 95 of file SampledFunction.h.

template<typename XType, typename YType>

using util::SampledFunction< XType, YType >::Y_t = YType

Type of value returned by the function.

Definition at line 96 of file SampledFunction.h.

Constructor & Destructor Documentation

template<typename XType, typename YType>

util::SampledFunction< XType, YType >::SampledFunction ( )

default

template<typename XType , typename YType >

template<typename Func >

util::SampledFunction< XType, YType >::SampledFunction	(	Func const &	function,
		X_t	lower,
		X_t	upper,
		gsl::index	nSamples,
		gsl::index	subsamples = 1
	)

Constructor: samples function in the specified range.

Template Parameters

Func	type of a functor (see requirements below)

Parameters

function	the function to be sampled
lower	the lower limit of the range to be sampled
upper	the upper limit of the range to be sampled
nSamples	the number (N) of samples to be computed
subsamples	(default: 1) the number (M) of subsamples to be computed

The sampling of function is performed on nSamples points from lower to upper (excluded).

The function parameter type Func need to be a unary functor, i.e. it must support a call of type function(X_t) const returning some value convertible to Y_t. Plain C functions and closures also work.

The function is not copied nor retained in any form, so it can be from a temporary object.

Definition at line 380 of file SampledFunction.h.

  : SampledFunction(
      Function_t(function),
      Range_t{ lower, upper, (upper - lower) / nSamples, nSamples },
      subsamples
    )
{}

template<typename XType , typename YType >

template<typename Func , typename UntilFunc >

util::SampledFunction< XType, YType >::SampledFunction	(	Func const &	function,
		X_t	lower,
		X_t	step,
		UntilFunc &&	until,
		gsl::index	subsamples,
		X_t	min_upper
	)

Constructor: samples function in the specified range.

Template Parameters

UntilFunc

type of functor indicating when to stop sampling

Parameters

function	the function to be sampled
lower	the lower limit of the range to be sampled
step	the sampling interval
until	functor to indicate when to stop sampling
subsamples	(default: 1) the number (M) of subsamples to be computed
min_upper	(default: none) minimum value covered by the sampling

The sampling of function is performed from lower, advancing by step at each following sample, until the until functor returns true. If min_upper is specified, regardless of the result of until, samples below min_upper are always covered.

The functor until should be callable as in bool until(X_t x, Y_t y), and should return false if the sample of value y, corresponding to the evaluation point x, needs to be sampled, and true if instead that sample needs to be discarded, and the sampling stopped. For example, to apply a threshold so that sampling stops when the function is 0.1, until can be defined as [](X_t, Y_t s){ return s >= Y_t{0.1}; } (x is ignored).

Subsampling is performed based on the subsamples argument.

Definition at line 397 of file SampledFunction.h.

  : SampledFunction(
      Function_t(function),
      extendRange
        (function, lower, min_upper, step, std::forward<UntilFunc>(until)),
      subsamples
    )
{}

template<typename XType, typename YType>

template<typename Func , typename UntilFunc >

util::SampledFunction< XType, YType >::SampledFunction	(	Func const &	function,
		X_t	lower,
		X_t	step,
		UntilFunc &&	until,
		gsl::index	subsamples = 1
	)

template<typename XType , typename YType >

util::SampledFunction< XType, YType >::SampledFunction ( Function_t const &  function, Range_t const &  range, gsl::index  subsamples  )

private

Constructor implementation.

Definition at line 460 of file SampledFunction.h.

  : fLower(range.lower)
  , fUpper(range.upper)
  , fNSamples(range.nSamples)
  , fNSubsamples(subsamples)
  , fStep(range.step)
  , fAllSamples(computeTotalSize())
{
  assert(fNSamples > 0);
  assert(subsamples > 0);
  fillSamples(function);
} // util::SampledFunction<>::SampledFunction(range)

Member Function Documentation

template<typename XType , typename YType >

gsl::index util::SampledFunction< XType, YType >::closestSubsampleIndex

(

X_t

x

)

const

Returns the subsample closest to the value x.

Parameters

x	value to be checked

Returns

the index of the subsample found

The subsample with the bin including x whose lower bound is the closest to x itself is returned.

For example, assuming bins aligned with 0 and a sampling with steps of size 1 and 5 subsamples, there will be 5 bins contaning the value x 3.65: [ 3.0, 4.0 ], [ 3.2, 4.2 ], [ 3.4, 4.4 ], [ 3.6, 4.6 ] and [ 2.8, 3.8 ], one for each subsample: closestSubsampleIndex(3.65) will return the sample with the bin 3.6, 4.6, because its lower bound 3.6 is the closest to 3.65.

The value x does not need to be in the sampling range. In the example above, the range could have been between 0 and 2, and the result would be the same.

Definition at line 425 of file SampledFunction.h.

{
  auto const dx = static_cast<double>(x - lower());
  auto const step = static_cast<double>(stepSize());
  auto const substep = static_cast<double>(substepSize());
  return static_cast<gsl::index>(wrapUp(std::fmod(dx, step), step) / substep);
} // gsl::index util::SampledFunction<XType, YType>::stepIndex()

template<typename XType, typename YType>

std::size_t util::SampledFunction< XType, YType >::computeTotalSize ( ) const

inlineprivate

Computes the total size of the data.

Definition at line 333 of file SampledFunction.h.

{ return nSubsamples() * size(); }

template<typename XType , typename YType >

template<typename Stream >

void util::SampledFunction< XType, YType >::dump	(	Stream &&	out,
		std::string const &	indent,
		std::string const &	firstIndent
	)		const

Dumps the full content of the sampling into out stream.

Definition at line 438 of file SampledFunction.h.

{
  out << firstIndent << "Function sampled from " << lower() << " to " << upper()
    << " (extent: " << rangeSize() << ")"
    << " with " << size() << " samples (" << stepSize() << " long)";
  if (nSubsamples() > 1) {
    out << " and " << nSubsamples() << " subsamples (" << substepSize()
      << " long):";
  }
  for (auto const iSub: util::counter(nSubsamples())) {
    out << "\n" << indent << "<subsample #" << iSub << ">:";
    // FIXME with C++20's `std::span` temporary won't be needed any more
    auto const& sub = subsample(iSub);
    for (auto const [ i, sample ]: util::enumerate(sub))
      out << " [" << i << "] " << sample;
  } // for
  out << "\n";
} // util::SampledFunction<>::dump()

template<typename XType, typename YType>

template<typename Stream >

void util::SampledFunction< XType, YType >::dump ( Stream &&  out, std::string const &  indent = ""  ) const

inline

Dumps the full content of the sampling into out stream.

Definition at line 293 of file SampledFunction.h.

    { dump(std::forward<Stream>(out), indent, indent); }

template<typename XType, typename YType>

template<typename UntilFunc >

static Range_t util::SampledFunction< XType, YType >::extendRange ( Function_t const &  function, X_t  lower, X_t  min_upper, X_t  step, UntilFunc &&  until  )

staticprivate

Returns a range including at least from lower to min_upper, extended enough that until(upper, f(upper)) is true, and with an integral number of steps.

template<typename XType, typename YType>

template<typename UntilFunc >

auto util::SampledFunction< XType, YType >::extendRange	(	Function_t const &	function,
		X_t	lower,
		X_t	min_upper,
		X_t	step,
		UntilFunc &&	until
	)		-> Range_t

Definition at line 481 of file SampledFunction.h.

{
  assert(min_upper >= lower);
  auto const startSamples
    = static_cast<gsl::index>(std::ceil((min_upper - lower) / step));

  auto const endStep
    = [lower, step](gsl::index iStep){ return lower + step * iStep; };

  Range_t r { lower, endStep(startSamples), step, startSamples };

  while (!until(r.upper + r.step, function(r.upper + r.step))) {
    // upper + step is not too much: extend to there
    ++r.nSamples;
    r.upper = endStep(r.nSamples);
  } // while

  return r;
} // util::SampledFunction<>::extendRange()

template<typename XType , typename YType >

void util::SampledFunction< XType, YType >::fillSamples ( Function_t const &  function )

private

Samples the function and fills the internal caches.

Definition at line 508 of file SampledFunction.h.

{

  /*
   * Plan:
   * 0. rely on the currently stored size specifications (range and samples)
   * 1. resize the data structure to the required size
   * 2. fill all the subsamples, in sequence
   *
   */

  //
  // 0. rely on the currently stored size specifications (range and samples)
  //
  std::size_t const dataSize = computeTotalSize();
  assert(dataSize > 0U);
  assert(fLower <= fUpper);
  assert(fStep > X_t{0});

  //
  // 1. resize the data structure to the required size
  //
  fAllSamples.resize(dataSize);

  //
  // 2. fill all the subsamples, in sequence
  //
  auto iValue = fAllSamples.begin();
  for (gsl::index const iSubsample: util::counter(nSubsamples())) {
    X_t const offset = subsampleOffset(iSubsample);
    for (gsl::index const iStep: util::counter(size())) {
      X_t const x = offset + iStep * stepSize();
      Y_t const y = function(x);
      *iValue++ = y;
    } // for steps
  } // for subsamples

} // util::SampledFunction<>::fillSamples()

template<typename XType, typename YType>

bool util::SampledFunction< XType, YType >::isValidStepIndex ( gsl::index const  index ) const

inline

Returns whether the specified step index is valid.

Definition at line 255 of file SampledFunction.h.

    { return (index >= 0) && (index < size()); }

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::lower ( ) const

inline

Returns the lower limit of the covered range.

Definition at line 193 of file SampledFunction.h.

{ return fLower; }

template<typename XType, typename YType>

gsl::index util::SampledFunction< XType, YType >::nSubsamples ( ) const

inline

Returns the number of subsamples.

Definition at line 188 of file SampledFunction.h.

{ return fNSubsamples; }

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::rangeSize ( ) const

inline

Returns the extension of the covered range.

Definition at line 203 of file SampledFunction.h.

{ return upper() - lower(); }

template<typename XType, typename YType>

gsl::index util::SampledFunction< XType, YType >::size ( ) const

inline

Returns the number of samples (in each subsample).

Definition at line 183 of file SampledFunction.h.

{ return fNSamples; }

template<typename XType , typename YType >

gsl::index util::SampledFunction< XType, YType >::stepIndex	(	X_t const	x,
		gsl::index const	iSubsample
	)		const

Returns the index of the step including x.

Parameters

x	the argument to the function
iSubsample	the index of the subsample

Returns

the index of step including x, or npos if none does

This function returns the index of the sample whose step includes x. A step includes its lower limit but not its upper limit, which usually belongs to the next step (or it does not belong to any valid step). If there is no step including x, the index of the would-be step is returned (it can be checked e.g. with isValidStepIndex()).

Definition at line 415 of file SampledFunction.h.

{
  auto const dx = static_cast<double>(x - subsampleOffset(iSubsample));
  return static_cast<gsl::index>(std::floor(dx / stepSize()));
} // gsl::index util::SampledFunction<XType, YType>::stepIndex()

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::stepSize ( ) const

inline

Returns the extension of a step.

Definition at line 208 of file SampledFunction.h.

{ return fStep; }

template<typename XType, typename YType>

SubsampleData_t util::SampledFunction< XType, YType >::subsample ( gsl::index const  n ) const

inline

Returns the data of the subsample with the specified index n.

Definition at line 233 of file SampledFunction.h.

    { return { subsampleData(n), static_cast<std::size_t>(fNSamples) }; }

template<typename XType, typename YType>

Y_t const* util::SampledFunction< XType, YType >::subsampleData ( gsl::index  n ) const

inlineprivate

Start of the block of values for subsample n (unchecked).

Definition at line 327 of file SampledFunction.h.

    { return fAllSamples.data() + fNSamples * n; }

template<typename XType, typename YType>

Y_t* util::SampledFunction< XType, YType >::subsampleData ( gsl::index  n )

inlineprivate

Definition at line 329 of file SampledFunction.h.

{ return fAllSamples.data() + fNSamples * n; }

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::subsampleOffset ( gsl::index  n ) const

inlineprivate

Returns the starting point of the subsample n.

Definition at line 321 of file SampledFunction.h.

    { return lower() + substepSize() * n; }

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::substepSize ( ) const

inline

Returns the base offset of the subsamples.

Definition at line 213 of file SampledFunction.h.

{ return stepSize() / nSubsamples(); }

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::upper ( ) const

inline

Returns the upper limit of the covered range.

Definition at line 198 of file SampledFunction.h.

{ return fUpper; }

template<typename XType, typename YType>

Y_t util::SampledFunction< XType, YType >::value ( gsl::index  iSample, gsl::index  n = 0U  ) const

inline

Returns the iSample value of the subsample with the specified index n.

Definition at line 226 of file SampledFunction.h.

    { return subsampleData(n)[iSample]; }

template<typename XType , typename YType >

template<typename T >

T util::SampledFunction< XType, YType >::wrapUp ( T  value, T  range  )

staticprivate

Returns value made non-negative by adding multiples of range.

Definition at line 551 of file SampledFunction.h.

                                                            {
  while (value < T{ 0 }) value += range;
  return value;
} // util::SampledFunction<>::wrapUp()

Member Data Documentation

template<typename XType, typename YType>

std::vector<Y_t> util::SampledFunction< XType, YType >::fAllSamples

private

All samples, the entire first subsample first.

Definition at line 314 of file SampledFunction.h.

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::fLower

private

Lower limit of sampled range.

Definition at line 306 of file SampledFunction.h.

template<typename XType, typename YType>

gsl::index util::SampledFunction< XType, YType >::fNSamples

private

Number of samples in the range.

Definition at line 308 of file SampledFunction.h.

template<typename XType, typename YType>

gsl::index util::SampledFunction< XType, YType >::fNSubsamples

private

Number of subsamples.

Definition at line 309 of file SampledFunction.h.

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::fStep

private

Step size.

Definition at line 311 of file SampledFunction.h.

template<typename XType, typename YType>

X_t util::SampledFunction< XType, YType >::fUpper

private

Upper limit of sampled range.

Definition at line 307 of file SampledFunction.h.

template<typename XType, typename YType>

constexpr auto util::SampledFunction< XType, YType >::npos = std::numeric_limits<gsl::index>::max()

static

Invalid index of sample, returned in case of error.

Definition at line 100 of file SampledFunction.h.

---

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

• SampledFunction.h