/ 
Math-Histo-PDL-0.2.0
/ Math::Histo::PDL

NAME

Math::Histo::PDL - High-performance PDL integration and zero-copy ingestion for Math::Histo

SYNOPSIS

use PDL;
use Math::Histo;
use Math::Histo::PDL qw(:all);

# 1D Ingestion from PDL (Zero-Copy)
my $data = grandom(1_000_000);
my $h = hist1d($data, bins => 100, min => -5, max => 5);

# Weighted ingestion
my $weights = random(1_000_000);
$h->fill_pdl($data, $weights);

# Export 1D histogram to PDL piddles
my ($counts, $edges, $errors) = $h->to_pdl;
my $centers = $h->centers_pdl;

# 2D Ingestion from PDL
my $x = grandom(500_000);
my $y = grandom(500_000);
my $h2d = hist2d($x, $y, xbins => 50, ybins => 50);

# 2D Ingestion from Nx2 or 2xN coordinate matrix
my $coords = grandom(2, 500_000);
my $h2d_mat = hist2d($coords, bins => 50);

# Export 2D histogram to PDL matrix and axis vectors
my ($matrix, $x_edges, $y_edges) = $h2d->to_pdl;
my $x_centers = $h2d->x_centers_pdl;
my $y_centers = $h2d->y_centers_pdl;

DESCRIPTION

Math::Histo::PDL provides seamless, bidirectional integration between PDL (Perl Data Language) and Math::Histo / Math::Histo::2D.

It is designed for maximum numerical throughput:

  • Zero-Copy Ingestion: For double-precision contiguous piddles, Math::Histo::PDL leverages $pdl-get_dataref> to pass underlying C buffers directly into Math::Histo's SIMD-accelerated C core (fill_packed_f64).

  • Transparent Coercion: Non-double data types (e.g. long, float) or non-contiguous slices (e.g. strided or transposed piddles) are automatically and cleanly converted to physical double buffers.

  • Idiomatic OO and Functional APIs: When loaded, Math::Histo::PDL automatically attaches to_pdl, fill_pdl, and axis export methods directly onto Math::Histo and Math::Histo::2D, alongside convenience builder functions (hist1d, hist2d, pdl_to_histo, histo_to_pdl).

FUNCTIONS

1D Histogramming

hist1d($data, %opts)

Creates and fills a Math::Histo 1D histogram from a PDL piddle $data.

Options:

  • bins / nbins: Number of bins (default: 50).

  • min, max: Range minimum and maximum. Defaults to data min/max if omitted.

  • edges: Arrayref or 1D piddle of custom variable bin edges.

  • rule / auto: Automatic bin estimation rule ('fd', 'scott', 'sturges', 'doane', 'knuth', 'auto').

  • weights: Optional 1D weights piddle of matching length.

  • sumw2 / track_sumw2: Track sum of squared weights for error propagation.

fill_pdl($h, $data, [$weights])

Fills an existing Math::Histo histogram with elements from $data and optional $weights. Returns $h for method chaining.

counts_pdl($h)

Returns a 1D double PDL piddle containing the bin contents (size $h->nbins).

edges_pdl($h)

Returns a 1D double PDL piddle containing all bin edges (size $h->nbins + 1).

centers_pdl($h)

Returns a 1D double PDL piddle containing the bin center coordinates (size $h->nbins).

errors_pdl($h)

Returns a 1D double PDL piddle containing the statistical uncertainties / standard errors per bin.

to_pdl($h, %opts)

In list context: returns ($counts, $edges, $errors). In scalar context: returns $counts. If all => 1 is passed: returns a hashref containing counts, edges, centers, errors.

2D Histogramming

hist2d($x, $y, %opts) or hist2d($coords, %opts)

Creates and fills a Math::Histo::2D histogram from coordinate piddles ($x, $y) or a 2D coordinate matrix $coords (having shape (2, N) or (N, 2)).

Options:

  • xbins, ybins (or bins => [$nx, $ny] or bins => $n): Bin counts per axis.

  • xmin, xmax, ymin, ymax: Axis bounds. Defaults to data min/max if omitted.

  • xedges, yedges: Custom variable bin edges per axis.

  • weights: Optional weights piddle.

fill2d_pdl($h2d, $x, $y, [$weights]) or fill2d_pdl($h2d, $coords, [$weights])

Fills an existing 2D histogram from coordinate piddles. Returns $h2d.

matrix_pdl($h2d) (alias counts_pdl)

Returns a 2D double PDL matrix of shape (nx, ny) containing the 2D bin contents.

x_edges_pdl($h2d) / y_edges_pdl($h2d)

Returns 1D double PDL piddles of X and Y bin edges (sizes nx + 1 and ny + 1).

x_centers_pdl($h2d) / y_centers_pdl($h2d)

Returns 1D double PDL piddles of X and Y bin centers.

errors2d_pdl($h2d)

Returns a 2D double PDL matrix of shape (nx, ny) of bin errors.

to_pdl2d($h2d, %opts)

In list context: returns ($matrix, $x_edges, $y_edges). In scalar context: returns $matrix. If all => 1 is passed: returns a hashref containing matrix, x_edges, y_edges, x_centers, y_centers, errors.

OBJECT-ORIENTED EXTENSIONS

When Math::Histo::PDL is loaded, the following methods are added:

Methods on Math::Histo

  • $h->fill_pdl($data, [$weights])

  • $h->to_pdl(%opts)

  • $h->counts_pdl

  • $h->edges_pdl

  • $h->centers_pdl

  • $h->errors_pdl

Methods on Math::Histo::2D

  • $h2d->fill_pdl($x, $y, [$weights]) / $h2d->fill_pdl($coords, [$weights])

  • $h2d->to_pdl(%opts)

  • $h2d->matrix_pdl / $h2d->counts_pdl

  • $h2d->x_edges_pdl / $h2d->y_edges_pdl

  • $h2d->x_centers_pdl / $h2d->y_centers_pdl

  • $h2d->errors_pdl

PERFORMANCE CONSIDERATIONS

To achieve zero-copy filling into libhisto:

1. Ensure your input piddle is of type double (e.g. $pdl->double or created as zeros(double, ...)).
2. Avoid passing deeply sliced non-physical views directly in hot loops if maximum throughput is required; Math::Histo::PDL will automatically call make_physical when needed.

SEE ALSO

Math::Histo, Math::Histo::2D, PDL

AUTHOR

Steffen Mueller <cpan@steffen-mueller.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Steffen Mueller.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself (MIT License).