Issue 794: piecewise_constant_distribution missing constructor

This page is a snapshot from the LWG issues list, see the Library Active Issues List for more information and the meaning of Resolved status.

794. `piecewise_constant_distribution` missing constructor

Section: 28.5.9.6.2 [rand.dist.samp.pconst] Status: Resolved Submitter: P.J. Plauger Opened: 2008-02-09 Last modified: 2016-01-28

Priority: Not Prioritized

View all other issues in [rand.dist.samp.pconst].

View all issues with Resolved status.

Discussion:

piecewise_constant_distribution should have a constructor like:

template<class _Fn>
   piecewise_constant_distribution(size_t _Count,
            _Ty _Low, _Ty _High, _Fn& _Func);

(Makes it easier to fill a histogram with function values over a range. The two (reference 793) make a sensible replacement for general_pdf_distribution.)

[ Sophia Antipolis: ]

Marc: uses variable width of bins and weight for each bin. This is not giving enough flexibility to control both variables.

Add a library issue to provide an constructor taking an initializer_list<double> and _Fn for piecewise_constant_distribution.

Daniel to draft wording.

[ Pre San Francisco, Daniel provided wording. ]

The here proposed changes of the WP refer to the current state of N2691. For reasons explained in 793, the author decided to propose a function argument that is provided by value. The issue proposes a c'tor signature, that does not take advantage of the full flexibility of piecewise_constant_distribution, because it restricts on a constant bin width, but the use-case seems to be popular enough to justify it's introduction.

Proposed resolution:

Non-concept version of the proposed resolution

In 28.5.9.6.2 [rand.dist.samp.pconst]/1, class piecewise_constant_distribution, just before the member declaration

explicit piecewise_constant_distribution(const param_type& parm);

insert:

template<typename Func>
piecewise_constant_distribution(size_t nf, RealType xmin, RealType xmax, Func fw);

Between p.4 and p.5 insert a new sequence of paragraphs nominated below as [p5_1], [p5_2], [p5_3], and [p5_4] as part of the new member description:
```
template<typename Func>
piecewise_constant_distribution(size_t nf, RealType xmin, RealType xmax, Func fw);
```
[p5_1] Complexity: Exactly nf invocations of fw.

[p5_2] Requires:
1. fw shall be callable with one argument of type RealType, and shall return values of a type convertible to double;
2. For all sample values x_k defined below, fw(x_k) shall return a weight value w_k that is non-negative, non-NaN, and non-infinity;
3. The following relations shall hold: x_min < x_max, and 0 < S = w₀+. . .+w_n-1.
[p5_3] Effects:
1. If nf == 0,
  1. sets deltax = x_max - x_min, and
  2. lets the sequence w have length n = 1 and consist of the single value w₀ = 1, and
  3. lets the sequence b have length n+1 with b₀ = x_min and b₁ = x_max
2. Otherwise,
  1. sets n = nf, deltax = (x_max - x_min)/n, x_cent = x_min + 0.5 * deltax, and
  2. lets the sequences w and b have length n and n+1, resp. and
    for each k = 0, . . . ,n-1, calculates:
    dx_k = k * deltax b_k = x_min + dx_k x_k = x_cent + dx_k w_k = fw(x_k),
    
    and
  3. sets b_n = x_max
3. Constructs a piecewise_constant_distribution object with the above computed sequence b as the interval boundaries and with the probability densities:
  
  ρ_k = w_k/(S * deltax) for k = 0, . . . , n-1.
[p5_4] [Note: In this context, the subintervals [b_k, b_k+1) are commonly known as the bins of a histogram. -- end note]

Concept version of the proposed resolution

In 28.5.9.6.2 [rand.dist.samp.pconst]/1, class piecewise_constant_distribution, just before the member declaration

explicit piecewise_constant_distribution(const param_type& parm);

insert:

template<Callable<auto, RealType> Func>
 requires Convertible<Func::result_type, double>
piecewise_constant_distribution(size_t nf, RealType xmin, RealType xmax, Func fw);

Between p.4 and p.5 insert a new sequence of paragraphs nominated below as [p5_1], [p5_2], [p5_3], and [p5_4] as part of the new member description:
```
template<Callable<auto, RealType> Func>
 requires Convertible<Func::result_type, double>
piecewise_constant_distribution(size_t nf, RealType xmin, RealType xmax, Func fw);
```
[p5_1] Complexity: Exactly nf invocations of fw.

[p5_2] Requires:
1. For all sample values x_k defined below, fw(x_k) shall return a weight value w_k that is non-negative, non-NaN, and non-infinity;
2. The following relations shall hold: x_min < x_max, and 0 < S = w₀+. . .+w_n-1.
[p5_3] Effects:
1. If nf == 0,
  1. sets deltax = x_max - x_min, and
  2. lets the sequence w have length n = 1 and consist of the single value w₀ = 1, and
  3. lets the sequence b have length n+1 with b₀ = x_min and b₁ = x_max
2. Otherwise,
  1. sets n = nf, deltax = (x_max - x_min)/n, x_cent = x_min + 0.5 * deltax, and
  2. lets the sequences w and b have length n and n+1, resp. and
    for each k = 0, . . . ,n-1, calculates: dx_k = k * deltax b_k = x_min + dx_k x_k = x_cent + dx_k w_k = fw(x_k),
    
    and
  3. sets b_n = x_max
3. Constructs a piecewise_constant_distribution object with the above computed sequence b as the interval boundaries and with the probability densities:
  
  ρ_k = w_k/(S * deltax) for k = 0, . . . , n-1.
[p5_4] [Note: In this context, the subintervals [b_k, b_k+1) are commonly known as the bins of a histogram. -- end note]

Rationale:

Addressed by N2836 "Wording Tweaks for Concept-enabled Random Number Generation in C++0X".

794. piecewise_constant_distribution missing constructor

794. `piecewise_constant_distribution` missing constructor