Trailing-axis shape compatibility and element projection. More...

#include <algorithm>
#include <cstddef>
#include <vector>
#include <stratax/core/dtypes/Concepts.hpp>
#include <stratax/exceptions/Exceptions.hpp>
#include <stratax/core/Shape.hpp>
#include <stratax/core/ArrayTraits.hpp>
#include <stratax/core/dtypes/Promotion.hpp>

Include dependency graph for Broadcasting.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
std::size_t	stratax::core::broadcast_detail::dimension_from_right (const Shape &shape, std::size_t offset)
	Returns a shape dimension counted from the trailing axis.

std::size_t	stratax::core::broadcast_detail::flat_operand_index (std::size_t result_index, const stratax::core::Shape &result_shape, const stratax::core::Shape &operand_shape)
	Maps a flat result index to the corresponding operand index.

bool	broadcastable (const stratax::core::Shape &shape1, const stratax::core::Shape &shape2)
	Tests whether two shapes satisfy trailing-dimension broadcasting.

stratax::core::Shape	broadcasted_shape (const stratax::core::Shape &shape1, const stratax::core::Shape &shape2)
	Computes the common shape produced by broadcasting two shapes.

template<Array L, Array R>
Shape	stratax::core::broadcast_detail::array_result_shape (const L &lhs, const R &rhs)
	Validates shape broadcasting and the availability of operand values.

template<DType Result, Array L, Array R, typename Op >
auto	stratax::core::broadcasted_op (const L &lhs, const R &rhs, Op op)
	Applies a binary callable with broadcasting and an explicit result dtype.

template<Array L, Array R, typename Op > requires ( Numeric<typename L::value_type> && Numeric<typename R::value_type> )
auto	stratax::core::broadcasted_op (const L &lhs, const R &rhs, Op op)
	Applies a binary callable using the operands' promoted dtype.

template<Array L, Numeric S, typename Op >
auto	broadcasted_op (const L &lhs, const S &rhs, Op op)
	Applies a binary callable to every array element and a right scalar.

template<Numeric S, Array R, typename Op >
auto	broadcasted_op (const S &lhs, const R &rhs, Op op)
	Applies a binary callable to a left scalar and every array element.

Detailed Description

Trailing-axis shape compatibility and element projection.

Definition in file Broadcasting.hpp.

Function Documentation

◆ array_result_shape()

template<Array L, Array R>

Shape stratax::core::broadcast_detail::array_result_shape	(	const L &	lhs,
		const R &	rhs
	)

Validates shape broadcasting and the availability of operand values.

Returns: Common broadcasted shape.

Exceptions

Exceptions::BroadcastError If shapes are incompatible or an empty operand would need to supply values to a nonempty result.

Complexity: O(lhs.rank() + rhs.rank()).

Definition at line 190 of file Broadcasting.hpp.

◆ broadcastable()

bool broadcastable	(	const stratax::core::Shape &	shape1,
		const stratax::core::Shape &	shape2
	)

inline

Tests whether two shapes satisfy trailing-dimension broadcasting.

Shapes are aligned from the right. Each aligned pair is compatible when the dimensions are equal or either dimension is one. Missing leading dimensions behave as though they were one. A zero dimension therefore broadcasts with zero or one, but not with a different non-singleton extent.

Rank-zero shapes contain no conflicting axes and are therefore compatible with every shape under these rules.

Parameters

shape1	First candidate shape.
shape2	Second candidate shape.

Returns: true when the shapes can be broadcast together; otherwise false.

Complexity: O(max(shape1.rank(), shape2.rank())).

Definition at line 114 of file Broadcasting.hpp.

◆ broadcasted_op() [1/4]

template<DType Result, Array L, Array R, typename Op >

auto stratax::core::broadcasted_op	(	const L &	lhs,
		const R &	rhs,
		Op	op
	)

Applies a binary callable with broadcasting and an explicit result dtype.

Template Parameters

Result	Dtype to which each callable result is converted.
L	Left owning array type with a PromoteArray specialization.
R	Right owning array type with a PromoteArray specialization.
Op	Callable accepting the original operand element types.

Parameters

lhs	Left operand.
rhs	Right operand.
op	Callable invoked once per result element in logical flat order.

Returns: Owning array; same-family inputs preserve that family, mixed families produce a Tensor.

Exceptions

Exceptions::BroadcastError If shapes are incompatible or an empty operand would supply values to a nonempty result.

Note: Allocation and callable exceptions propagate. Operands are not cast to Result before calling op.

Complexity: O((n + 1) * r), where n is result size and r is result rank.

Definition at line 221 of file Broadcasting.hpp.

◆ broadcasted_op() [2/4]

template<Array L, Array R, typename Op >
requires ( Numeric<typename L::value_type> && Numeric<typename R::value_type> )

auto stratax::core::broadcasted_op	(	const L &	lhs,
		const R &	rhs,
		Op	op
	)

Applies a binary callable using the operands' promoted dtype.

This overload preserves the inferred array-array API while forwarding to the explicit-result overload used by operations that require a custom result dtype.

Returns: Owning promoted array with the common broadcasted shape.

Exceptions

Exceptions::BroadcastError If shapes are incompatible or an empty operand would supply values to a nonempty result.

Complexity: O((n + 1) * r), where n is result size and r is result rank.

Definition at line 271 of file Broadcasting.hpp.

◆ broadcasted_op() [3/4]

template<Array L, Numeric S, typename Op >

auto broadcasted_op	(	const L &	lhs,
		const S &	rhs,
		Op	op
	)

Applies a binary callable to every array element and a right scalar.

The result preserves L's container family and shape, uses the dtype selected by promote_t<L::value_type, S>, and owns independent storage. Each callable result is converted to the promoted dtype. If lhs is empty, the callable is never invoked.

Template Parameters

L	Stratax array type and result container family.
S	Numeric scalar type participating in dtype promotion.
Op	Binary callable invocable with `L::value_type` and `S` and whose result is convertible to the promoted dtype.

Parameters

lhs	Array supplying each left argument.
rhs	Scalar supplied as every right argument.
op	Callable invoked as `op(lhs[i], rhs)`.

Returns: Owning array with L's container family, the promoted dtype, and the same shape as lhs.

Exceptions

std::bad_alloc	If result storage allocation fails.
Any	exception propagated by result construction, conversion, or `op`.

Complexity: O(lhs.size()).

Note: No shape broadcasting or index projection is required for a scalar.; lhs is not modified.

Definition at line 314 of file Broadcasting.hpp.

◆ broadcasted_op() [4/4]

template<Numeric S, Array R, typename Op >

auto broadcasted_op	(	const S &	lhs,
		const R &	rhs,
		Op	op
	)

Applies a binary callable to a left scalar and every array element.

The result preserves R's container family and shape, uses the dtype selected by promote_t<S, R::value_type>, and owns independent storage. Operand order is preserved when invoking op, which matters for non-commutative callables. Each callable result is converted to the promoted dtype. If rhs is empty, the callable is never invoked.

Template Parameters

S	Numeric scalar type participating in dtype promotion.
R	Stratax array type and result container family.
Op	Binary callable invocable with `S` and `R::value_type` and whose result is convertible to the promoted dtype.

Parameters

lhs	Scalar supplied as every left argument.
rhs	Array supplying each right argument.
op	Callable invoked as `op(lhs, rhs[i])`.

Returns: Owning array with R's container family, the promoted dtype, and the same shape as rhs.

Exceptions

std::bad_alloc	If result storage allocation fails.
Any	exception propagated by result construction, conversion, or `op`.

Complexity: O(rhs.size()).

Note: No shape broadcasting or index projection is required for a scalar.; rhs is not modified.

Definition at line 363 of file Broadcasting.hpp.

◆ broadcasted_shape()

stratax::core::Shape broadcasted_shape	(	const stratax::core::Shape &	shape1,
		const stratax::core::Shape &	shape2
	)

inline

Computes the common shape produced by broadcasting two shapes.

Compatible dimensions are aligned from the right. For each result axis, a singleton extent yields to the other extent; otherwise the equal extent is retained. Consequently, zero broadcasts with one to produce zero. The operation is symmetric: swapping the arguments produces the same shape. If both arguments have rank zero, the returned shape also has rank zero.

Parameters

shape1	First operand shape.
shape2	Second operand shape.

Returns: Common broadcasted shape.

Exceptions

Exceptions::BroadcastError	If shapes are incompatible or an empty operand would supply values to a nonempty result.
std::bad_alloc	If result-dimension storage cannot be allocated.

Complexity: O(max(shape1.rank(), shape2.rank())).

Definition at line 153 of file Broadcasting.hpp.

◆ dimension_from_right()

std::size_t stratax::core::broadcast_detail::dimension_from_right	(	const Shape &	shape,
		std::size_t	offset
	)

inline

Returns a shape dimension counted from the trailing axis.

Missing leading dimensions are treated as singleton dimensions, which is equivalent to left-padding a lower-rank shape with ones for broadcasting. This helper does not allocate and does not validate offset.

Parameters

shape	Shape to query.
offset	Zero-based distance from the final dimension.

Returns: The selected dimension, or one when offset exceeds the rank.

Invariant: The input shape is never modified.

Complexity: O(1).

Definition at line 32 of file Broadcasting.hpp.

◆ flat_operand_index()

std::size_t stratax::core::broadcast_detail::flat_operand_index	(	std::size_t	result_index,
		const stratax::core::Shape &	result_shape,
		const stratax::core::Shape &	operand_shape
	)

inline

Maps a flat result index to the corresponding operand index.

The result index is decoded into row-major coordinates from the final axis toward the first. Coordinates on singleton operand dimensions collapse to zero, causing the corresponding value to be reused. Leading result axes that do not exist in the lower-rank operand are ignored as if the operand had leading singleton dimensions.

Parameters

result_index	Flat row-major index in the broadcasted result.
result_shape	Shape of the broadcasted result.
operand_shape	Broadcast-compatible shape of one operand.

Returns: Flat row-major index of the operand value used at result_index.

Precondition: result_index < result_shape.elements().; Every dimension of result_shape is nonzero. Empty broadcast results never call this helper.; operand_shape is broadcast-compatible with result_shape and does not have greater rank than result_shape.

Note: No bounds or compatibility checks are performed.

Invariant: The result and operand shapes are never modified.

Complexity: O(result_shape.rank()).

Definition at line 64 of file Broadcasting.hpp.

Functions

Detailed Description

Function Documentation

◆ array_result_shape()

◆ broadcastable()

◆ broadcasted_op() [1/4]

◆ broadcasted_op() [2/4]

◆ broadcasted_op() [3/4]

◆ broadcasted_op() [4/4]

◆ broadcasted_shape()

◆ dimension_from_right()

◆ flat_operand_index()