feat: add math/base/special/atan2f

[anandkaranubc]

Progresses #649

Description

What is the purpose of this pull request?

This pull request:

• Adds the complete implementation for math/base/special/atan2f

Related Issues

Does this pull request have any related issues?

This pull request:

• Progresses [RFC]: Add C implementations to base special math functions (tracking issue) #649

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

---

@stdlib-js/reviewers

[anandkaranubc]

/stdlib update-copyright-years

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
math/base/special/atan2f	$\color{green}318/318$ $\color{green}+100.00\%$	$\color{green}26/26$ $\color{green}+100.00\%$	$\color{green}2/2$ $\color{green}+100.00\%$	$\color{green}318/318$ $\color{green}+100.00\%$

The above coverage report was generated for the changes in this PR.

[anandkaranubc]

I looked at the other reference implementations as well like cephes and Julia. In my opinion, they have similar implementations. Maybe our implementation is more verbose in terms of inf checks.

That's why I ended up using the same reference implementation we used for atan2

[Planeshifter]

I believe this should be Apache-2.0 AND BSD-3-Clause to cover the Go license is in the LICENSE file.

This likely also applies to other packages containing code ported from Go.

cc @kgryte

[Planeshifter]

Doing a search across the codebase, I am seeing that we are not consistent at all on whether the SPDX expression in the license field matches the licenses in LICENSE. Sometimes it does, sometimes it does not.

[anandkaranubc]

I can keep looking into the upcoming packages on the go and also update the double-precision ones if required.

[kgryte]

@Planeshifter @anandkaranubc This change should be reverted. The BSD-3-Clause does NOT require us to dual license; however, Boost does. Please confirm with me before making similar changes.

[anandkaranubc]

Reverting this change. Thanks for the feedback, @kgryte

[Planeshifter]

@kgryte I don't follow. Dual licensing usually refers to when a package offers the choice between multiple licenses for using the code, which corresponds to an "OR" SPDX expression and is unrelated to the topic at hand.

And one wouldn't use SPDX expressions only when forced to license one's own code under a different license. The doumentation for SPDX gives the following example:

there are situations where a single license identifier is not sufficient. A common example is when software is offered under a choice of one or more licenses (e.g., GPL-2.0-only OR BSD-3-Clause). Another example is when a set of licenses is needed to represent a binary program constructed by compiling and linking two (or more) different source files each governed by different licenses (e.g., LGPL-2.1-only AND BSD-3-Clause).

https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions

Vendoring code or linking against it (which we state in the LICENSE, "The library links against the following external libraries or contains
implementations from the following external libraries, which have their own
licenses") would fall in that territory where it would be appropriate to list both licenses in the license field.

I have now read the Boost
and BSD-3
licenses multiple times and I cannot see what you are referring to with respect to a dual licensing requirement for Boost. In fact, it seems to me that Boost is less restrictive because it doesn't require inclusion of the license when one ships machine-executable object code.

Some clarification on the rationale here would be appreciated.

[kgryte]

@Planeshifter We discussed this a long time ago wrt Boost.

1. Sorry. By dual-license, I meant multi-license.

2. Boost is more restrictive. We use AND to more fully comply with the terms of the Boost license. In particular,

...this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

The BSD license has no such clause. We are not shipping object code, so that point is not relevant here.

The only license where we use AND is Boost, full stop. Whether that is warranted or not may be another matter. Regardless, we do not do this for BSD or Cephes or fdlibm or MIT-licensed derivative works. If we did, we'd need to relicense the entire project, which is currently Apache AND Boost, which is not something we are going to do.

[Planeshifter]

Thanks for elaborating! I clearly have forgotten any previous discussions about this; but seems sensible and certainly not worth relitigating.

[kgryte]

In short, our interpretation then, and mine still now, is that we need to bubble up the BSL license and not the others, as the others only require attribution, copyright, and disclaimer. Boost, on the other hand, requires that the license grant be included in all derivative works. We decided early on that that meant going beyond attribution and actually explicitly stating that a package and its implementation is also governed by the Boost license. We did this through the SPDX identifier. Subsequently, the entire project itself was licensed accordingly in order to ensure that the license grant and its restriction is communicated to consumers.

If you want to get an attorney involved to tell me I am wrong, go for it.

That doesn't change the fact that BSL is the only license where we use multi-licensing.

[Planeshifter]

We have been including only one example in C source files:

Suggested change

	* @example
	* float v = stdlib_base_atan2f( 2.0f, 2.0f ); // => stdlib_base_atanf( 1.0f )
	* // returns ~0.785f
	*
	* @example
	* float v = stdlib_base_atan2f( 6.0f, 2.0f ); // => stdlib_base_atanf( 3.0f )
	* // returns ~1.249f
	*
	* @example
	* float v = stdlib_base_atan2f( -1.0f, -1.0f ); // => stdlib_base_atanf( 1.0f ) - π
	* // returns ~-2.356f
	*
	* @example
	* float v = stdlib_base_atan2f( 3.0f, 0.0f ); // => π/2
	* // returns ~1.571f
	*
	* @example
	* float v = stdlib_base_atan2f( -2.0f, 0.0f ); // => -π/2
	* // returns ~-1.571f
	*
	* @example
	* float v = stdlib_base_atan2f( 0.0f, 0.0f );
	* // returns 0.0f
	*
	* @example
	* float v = stdlib_base_atan2f( 3.0f, NaN );
	* // returns NaN
	*
	* @example
	* float v = stdlib_base_atan2f( NaN, 2.0f );
	* // returns NaN
	* @example
	* float v = stdlib_base_atan2f( 2.0f, 2.0f ); // => stdlib_base_atanf( 1.0f )
	* // returns ~0.785f

[anandkaranubc]

On it! Thanks @Planeshifter for the review!

[Planeshifter]

Looks great; left two small comments.

[stdlib-bot]

PR Commit Message

feat: add `math/base/special/atan2f`

PR-URL: https://github.com/stdlib-js/stdlib/pull/7081
Ref: https://github.com/stdlib-js/stdlib/issues/649

Co-authored-by: Athan Reines <[email protected]>
Co-authored-by: stdlib-bot <[email protected]>
Reviewed-by: Philipp Burckhardt <[email protected]>

Please review the above commit message and make any necessary adjustments.

⚠️ Action Required: This PR references tracking issues. Please update the PR description to replace any "Closes", "Fixes", or "Resolves" keywords with "Ref" when referencing these issues.