search

gap-system / gap

Main development repository for GAP - Groups, Algorithms, Programming, a System for Computational Discrete Algebra
https://www.gap-system.org
GNU General Public License v2.0
773 stars 160 forks source link

Improve documentation for functions for floats #1778

Open mtorpey opened 6 years ago

mtorpey commented 6 years ago

@markuspf and I were looking at the documentation for "mathematical operations" functions on floats, currently Section 19.2-1, and noticed it explains the functions quite poorly. It consists of a long list of function names with no explanation and the simple description "Usual mathematical functions."

The meanings of SinCos, Atan2, Log1p, Erf, ComplexI and others are unclear, and users who don't understand what they're supposed to mean can only find out by experimentation.

Perhaps there should be proper documentation for these functions.

stevelinton commented 6 years ago

It might be possible to document them simply by reference to the standard C functions that they "wrap".

fingolfin commented 6 years ago

I agree that the float documentation in GAP is lacking, although I feel compelled to point out that SinCos, Atan2, Log1p, Erf, all are fairly standard and established names -- I know all of them, and I hardly qualify as an expert in numerics. But that's no excuse to at least give one line of information. It would be great if somebody did that, there are plenty of places where one can learn what these names are, e.g.

I have no idea what ComplexI is, though, and looking at the float package, this is only implemented by MPC, where it is mapped to CXI_MPC. Looking at the code, my guess is that this is meant to return a new complex float value representing the imaginary unit i=sqrt(-1), in the same precision as the argument to ComplexI. Now that definitely should be documented; it also seems like it should be in a separate section, or perhaps not be in GAP at all, but rather just be part of the float package. Indeed, for the whole bit about complex floats, I don't see why it needs to be in GAP -- GAP provides the core machinery to input floats, but anything beyond machine floats could be handled by that package.

While we are at it, there is a subsection "19.2-4 Interval operations " which doesn't give the slightest hint as to what an "interval" is -- I only later realized there is also "19.5 Interval-specific methods", so I guess a good start would be to move 19.2-4 into that section. Here, too, I wonder why this is in GAP, and not in the float package. GAP doesn't need to know about this.

I am going to submit a PR shortly which improves things a little bit, but some stuff remains mysterious to me. E.g. what is Overlaps for two intervals? Perhaps it returns a bool, with negated value of IsDisjoint? Then why are both needed? Also, the names are inconsistent -- perhaps IsDisjoint should be Disjoint? But that might also be confusing, so perhaps they should be called AreOverlapping / AreDisjoint ? (Of course even if we rename them, the old names would have to be retained as synonyms because existing code likely uses them)

Perhaps @laurentbartholdi has some thoughts on this, or counter arguments.

laurentbartholdi commented 6 years ago

Dear @Max: I gave some more thought to this -- indeed, what appears in GAP is a first shot at how to implement things. Some specific comments: -- ComplexI should disappear: it's rarely used, and can be obtained with NewFloat(ComplexFloatRep,0,1). -- Overlaps should also disappear too; its only implementation is "not IsDisjoint". I think it's OK to just nix these functions; since they're not documented, they should have been used only at the own risk of the users.

Now there's a standard that came out last year, IEEE 1788-2015 for interval arithmetic, and it would make sense to follow that standard as much as possible. I don't think I have the time to go into this too deeply, though. I'll try, nevertheless, to get hold of the standard and put in GAP the standard commands.

About what gets in GAP and what goes into float: my idea was the following. GAP would provide a standard interface, for complex, interval etc.; and packages would provide implementations. In some sense, GAP supplies all the "DeclareOperation" and packages supply "InstallMethod". This forces all float implementations to adhere to a common nomenclature. It also makes packages cleaner in that they don't have to all declare operations with restricted arguments to the new floateans. All this discussion is of course purely academic if there's only one floats package.

schnellecom commented 7 months ago

I have documented most of the functions discussed above in the PR https://github.com/gap-system/gap/pull/5530

However I was not able to find a definition for Erf(x). I assume it is the error function as described here: https://mathworld.wolfram.com/Erf.html https://en.wikipedia.org/wiki/Error_function But as I am unsure if e.g. the scalar factor in front is used and the function is imported from a C library I would like some clarification from someone more experienced than me.

laurentbartholdi commented 7 months ago

It's great that these functions get a bit more documented; and I'm definitely guilty for not having done my part. However, I don't understand the problem. Erf takes a single argument, and computes the Gaussian integral. These functions just declare methods, which are not implemented in GAP. They could in principle get implemented by the "Float" package, but for now they don't. They're part of the standard math library, see e.g. https://stackoverflow.com/questions/631629/erfx-and-math-h

On Mon, 13 Nov 2023 at 11:38, Lukas Schnelle @.***> wrote:

I have documented most of the functions discussed above in the PR #5530 https://github.com/gap-system/gap/pull/5530

However I was not able to find a definition for Erf(x). I assume it is the error function as described here: https://mathworld.wolfram.com/Erf.html https://en.wikipedia.org/wiki/Error_function But as I am unsure if e.g. the scalar factor in front is used and the function is implemented from a C library I would like some clarification from someone more experienced than me.

— Reply to this email directly, view it on GitHub https://github.com/gap-system/gap/issues/1778#issuecomment-1807902662, or unsubscribe https://github.com/notifications/unsubscribe-auth/AARAQUCKJ63IWC27GQVVLCDYEH2BZAVCNFSM4D7XDKK2U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TCOBQG44TAMRWGYZA . You are receiving this because you were mentioned.Message ID: @.***>

-- Laurent Bartholdi laurent.bartholdigmailcom Fachrichtung Informatik+Mathematik, Universität des Saarlandes Postfach 151150, 66041 Saarbrücken, Germany Tel. +49 681 3023227, Sekr. +49 681 3023430

schnellecom commented 7 months ago

Thank you for the clarification, I think I got it and made changes in PR https://github.com/gap-system/gap/pull/5530 accordingly. If no other functions are missing, this issue can be closed.