cuda::isclose()

[fbusato]

Description

Comparing two floating-point values is a widely used functionality. Every library that use floating-point values need to compare them at some point. CCCL used it too for internal testing.

Python has math.isclose() https://peps.python.org/pep-0485/, and numpy.isclose.
Several C++ testing frameworks and libraries provide a similar utility, GoogleTest, Catch2, Boost.Math, Eigen.

This PR introduces 3 overloads for isclose() following implementation decisions of math.isclose()

bool isclose(T lhs, T rhs);
bool isclose(T lhs, T rhs, float relative_tolerance);
bool isclose(T lhs, T rhs, float relative_tolerance, T absolute_tolerance);

we could also think to add interfaces based on C++20 designed initializer.

Supported types: integers, (extended) floating-point, complex (std. cuda, cuda::std).

Requires:

• Support __float128 for isfinite() and isinf() #9576

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds cuda::isclose for scalar and complex approximate-equality checks, wires it into cuda/numeric, and adds matching documentation and coverage tests.

Changes

cuda::isclose numeric utility

Layer / File(s)	Summary
Documentation docs/libcudacxx/extended_api/numeric.rst, docs/libcudacxx/extended_api/numeric/isclose.rst	Adds the new reference page, documents overloads and semantics, and registers the page in the numeric navigation and availability table.
Internal helpers libcudacxx/include/cuda/__numeric/isclose.h	Defines the comparison-type selector, default relative tolerance, overflow-safe integer difference, and the floating-point, complex, and integer implementations.
Public overloads and header wiring libcudacxx/include/cuda/__numeric/isclose.h, libcudacxx/include/cuda/numeric	Adds the public scalar and complex overloads, closes the namespace and include guard, and includes the new header from cuda/numeric.
Test coverage libcudacxx/test/libcudacxx/cuda/numeric/isclose/isclose.pass.cpp	Adds compile-time and runtime tests for floating-point, integral, and complex overloads, including invalid abs_tol cases and target-gated runtime coverage.

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🥳 CI Workflow Results

🟩 Finished in 1h 39m: Pass: 100%/120 | Total: 1d 20h | Max: 1h 32m | Hits: 92%/399559

See results here.

[davebayer]

Suggestion: In non-complex API we require absolute_tol to be of type T, but here it seems like it can have a different type than Complex::value_type.

I think we should rather do:

Suggested change

	template <class Complex, class AbsTol>
	[[nodiscard]] __host__ __device__
	bool isclose(const Complex& lhs,
	const Complex& rhs,
	float relative_tol,
	AbsTol absolute_tol) noexcept;
	template <class T>
	[[nodiscard]] __host__ __device__
	bool isclose(const /*complex-type*/<T>& lhs,
	const /*complex-type*/<T>& rhs,
	float relative_tol,
	T absolute_tol) noexcept;

What do you think?

[davebayer]

Would be gone if you accept my suggestion

[davebayer]

Suggested change

	_CCCL_TEMPLATE(typename _ComplexType, typename _AbsTol)
	_CCCL_REQUIRES(__isclose_complex_comparison_v<_ComplexType, _AbsTol>)
	[[nodiscard]] _CCCL_HOST_DEVICE_API bool
	isclose(const _ComplexType& __lhs, const _ComplexType& __rhs, const float __rel_tol, const _AbsTol __abs_tol) noexcept
	_CCCL_TEMPLATE(template <class> class _LhsComplex, template <class> class _RhsComplex, class _Tp)
	_CCCL_REQUIRES(::cuda::std::__cccl_is_integer_v<_Tp> || ::cuda::is_floating_point_v<_Tp>)
	[[nodiscard]] _CCCL_HOST_DEVICE_API bool
	isclose(const _LhsComplex<_Tp>& __lhs, const _RhsComplex<_Tp>& __rhs, const float __rel_tol, const _Tp __abs_tol) noexcept