Skip to content

Commit cd99a85

Browse files
juntyrSwayamInSync
juntyr
and
SwayamInSync
committed
Add API docs
Based on numpy/numpy-user-dtypes#256 Co-authored-by: swayaminsync <[email protected]>
1 parent a5b4f4b commit cd99a85

File tree

9 files changed

+865
-9
lines changed

9 files changed

+865
-9
lines changed

‎docs/api/constants_api.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Constants Reference
2+
3+
Pre-defined mathematical constants with quad precision accuracy.
4+
5+
## Mathematical Constants
6+
7+
```{eval-rst}
8+
.. data:: numpy_quaddtype.pi
9+
10+
The mathematical constant :math:`\pi` (pi).
11+
12+
:value: 3.14159265358979323846264338327950288...
13+
14+
:type: QuadPrecision
15+
16+
.. data:: numpy_quaddtype.e
17+
18+
Euler's number :math:`e`, the base of natural logarithms.
19+
20+
:value: 2.71828182845904523536028747135266249...
21+
22+
:type: QuadPrecision
23+
24+
.. data:: numpy_quaddtype.log2e
25+
26+
The base-2 logarithm of :math:`e`: :math:`\log_{2}{e}`.
27+
28+
:value: 1.44269504088896340735992468100189213...
29+
30+
:type: QuadPrecision
31+
32+
.. data:: numpy_quaddtype.log10e
33+
34+
The base-10 logarithm of :math:`e`: :math:`\log_{10}{e}`.
35+
36+
:value: 0.43429448190325182765112891891660508...
37+
38+
:type: QuadPrecision
39+
40+
.. data:: numpy_quaddtype.ln2
41+
42+
The natural logarithm of 2: :math:`\log_{e}{2}`.
43+
44+
:value: 0.69314718055994530941723212145817656...
45+
46+
:type: QuadPrecision
47+
48+
.. data:: numpy_quaddtype.ln10
49+
50+
The natural logarithm of 10: :math:`\log_{e}{10}`.
51+
52+
:value: 2.30258509299404568401799145468436420...
53+
54+
:type: QuadPrecision
55+
```
56+
57+
## Type Limits
58+
59+
```{eval-rst}
60+
.. data:: numpy_quaddtype.epsilon
61+
62+
Machine epsilon: the smallest positive number such that :math:`1.0 + \epsilon \neq 1.0`.
63+
64+
:value: :math:`2^{-112}` or approximately :math:`1.93 \cdot 10^{-34}`
65+
66+
:type: QuadPrecision
67+
68+
.. data:: numpy_quaddtype.max_value
69+
70+
The largest representable finite quad-precision value.
71+
72+
The largest negative representable finite quad-precision value is ``-numpy_quaddtype.max_value``.
73+
74+
:value: :math:`216383 \cdot (2 - 2^{-112})` or approximately :math:`1.19 \cdot 10^{4932}`
75+
76+
:type: QuadPrecision
77+
78+
.. data:: numpy_quaddtype.smallest_normal
79+
80+
The smallest positive normal (normalized, mantissa has a leading 1 bit) quad-precision value.
81+
82+
:value: :math:`2^{-16382} \cdot (1 - 2^{-112})` or approximately :math:`3.36 \cdot 10^{-4932}`
83+
84+
:type: QuadPrecision
85+
86+
.. data:: numpy_quaddtype.smallest_subnormal
87+
88+
The smallest positive subnormal (denormalized, mantissa has a leading 0 bit) quad-precision value.
89+
90+
:value: :math:`2^{-16494}` or approximately :math:`6.48 \cdot 10^{-4966}`
91+
92+
:type: QuadPrecision
93+
94+
.. data:: numpy_quaddtype.resolution
95+
96+
The approximate decimal resolution of quad precision, i.e. `10 ** (-precision)`.
97+
98+
:value: :math:`10^{-33}`
99+
100+
:type: QuadPrecision
101+
```
102+
103+
## Type Information
104+
105+
```{eval-rst}
106+
.. data:: numpy_quaddtype.bits
107+
108+
The total number of bits in quad precision representation.
109+
110+
:value: 128
111+
:type: int
112+
113+
.. data:: numpy_quaddtype.precision
114+
115+
The approximate number of significant decimal digits.
116+
117+
:value: 33
118+
:type: int
119+
```
120+
121+
## Example Usage
122+
123+
```python
124+
from numpy_quaddtype import (
125+
pi, e, log2e, log10e, ln2, ln10,
126+
epsilon, max_value, smallest_normal,
127+
bits, precision
128+
)
129+
130+
# Mathematical constants
131+
print(f"π = {pi}")
132+
print(f"e = {e}")
133+
134+
# Verify relationships
135+
import numpy as np
136+
from numpy_quaddtype import QuadPrecDType
137+
138+
# e^(ln2) should equal 2
139+
two = np.exp(np.array(ln2))
140+
print(f"e^(ln2) = {two}")
141+
142+
# log2(e) * ln(2) should equal 1
143+
one = log2e * ln2
144+
print(f"log2(e) × ln(2) = {one}")
145+
146+
# Type limits
147+
print(f"\nQuad precision uses {bits} bits")
148+
print(f"Approximately {precision} decimal digits of precision")
149+
print(f"Machine epsilon: {epsilon}")
150+
```

‎docs/api/core.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Core Types
2+
3+
The fundamental types provided by NumPy QuadDType.
4+
5+
## Quad Precision Value
6+
7+
```{eval-rst}
8+
.. class:: numpy_quaddtype.QuadPrecision(value, backend="sleef")
9+
10+
A quad-precision (128-bit) floating-point scalar.
11+
12+
QuadPrecision is a NumPy scalar type that provides IEEE 754 binary128
13+
floating-point arithmetic. It can be used standalone or as elements
14+
of NumPy arrays.
15+
16+
:param value: The value to convert to quad precision. It can be:
17+
18+
- ``float`` or ``int``: Python numeric types
19+
- ``str``: String representation for maximum precision
20+
- ``bytes``: Raw 16-byte representation
21+
- ``numpy.floating`` or ``numpy.integer``: NumPy numeric types
22+
- ``QuadPrecision``: Another QuadPrecision value
23+
:type value: float, int, str, bytes, numpy scalar, or QuadPrecision
24+
25+
:param backend: Computation backend to use. Either ``"sleef"`` (default)
26+
or ``"longdouble"``.
27+
:type backend: str, optional
28+
29+
**Examples**
30+
31+
Create from different input types::
32+
33+
>>> from numpy_quaddtype import QuadPrecision
34+
>>> QuadPrecision(3.14)
35+
QuadPrecision('3.14000000000000012434...')
36+
>>> QuadPrecision("3.14159265358979323846264338327950288")
37+
QuadPrecision('3.14159265358979323846264338327950288')
38+
>>> QuadPrecision(42)
39+
QuadPrecision('42.0')
40+
41+
Arithmetic operations::
42+
43+
>>> x = QuadPrecision("1.5")
44+
>>> y = QuadPrecision("2.5")
45+
>>> x + y
46+
QuadPrecision('4.0')
47+
>>> x * y
48+
QuadPrecision('3.75')
49+
50+
.. attribute:: dtype
51+
:type: QuadPrecDType
52+
53+
The NumPy dtype for this scalar.
54+
55+
.. attribute:: real
56+
:type: QuadPrecision
57+
58+
The real part (always self for QuadPrecision).
59+
60+
.. attribute:: imag
61+
:type: QuadPrecision
62+
63+
The imaginary part (always zero for QuadPrecision).
64+
```
65+
66+
## Quad Precision DType
67+
68+
```{eval-rst}
69+
.. class:: numpy_quaddtype.QuadPrecDType(backend="sleef")
70+
71+
NumPy dtype for quad-precision floating-point arrays.
72+
73+
QuadPrecDType is a custom NumPy dtype that enables the creation and
74+
manipulation of arrays containing quad-precision values.
75+
76+
:param backend: Computation backend. Either ``"sleef"`` (default) or
77+
``"longdouble"``.
78+
:type backend: str, optional
79+
80+
**Examples**
81+
82+
Create arrays with QuadPrecDType::
83+
84+
>>> import numpy as np
85+
>>> from numpy_quaddtype import QuadPrecDType
86+
>>> arr = np.array([1, 2, 3], dtype=QuadPrecDType())
87+
>>> arr.dtype
88+
QuadPrecDType128
89+
>>> np.zeros(5, dtype=QuadPrecDType())
90+
array([0.0, 0.0, 0.0, 0.0, 0.0], dtype=QuadPrecDType128)
91+
92+
.. attribute:: backend
93+
:type: QuadBackend
94+
95+
The computation backend (``SLEEF`` or ``LONGDOUBLE``).
96+
97+
.. attribute:: itemsize
98+
:type: int
99+
100+
The size of each element in bytes (always 16).
101+
102+
.. attribute:: alignment
103+
:type: int
104+
105+
The memory alignment in bytes (always 16).
106+
107+
.. attribute:: name
108+
:type: str
109+
110+
The string name of the dtype (``"QuadPrecDType128"``).
111+
```
112+
113+
```{eval-rst}
114+
.. class:: numpy_quaddtype.QuadBackend
115+
116+
Enumeration of available computation backends.
117+
118+
.. attribute:: SLEEF
119+
:value: 0
120+
121+
SLEEF library backend (default). Provides true IEEE 754 binary128
122+
quad precision with SIMD optimization.
123+
124+
.. attribute:: LONGDOUBLE
125+
:value: 1
126+
127+
The platform's native long double backend. The precision varies by platform.
128+
129+
**Example**
130+
131+
::
132+
133+
>>> from numpy_quaddtype import QuadPrecDType, QuadBackend
134+
>>> dtype = QuadPrecDType()
135+
>>> dtype.backend == QuadBackend.SLEEF
136+
True
137+
```
138+
139+
## Convenience Functions
140+
141+
```{eval-rst}
142+
.. function:: numpy_quaddtype.SleefQuadPrecision(value)
143+
144+
Create a QuadPrecision scalar using the SLEEF backend.
145+
146+
Equivalent to ``QuadPrecision(value, backend="sleef")``.
147+
148+
:param value: Value to convert to quad precision.
149+
:return: Quad precision scalar using SLEEF backend.
150+
:rtype: QuadPrecision
151+
```
152+
153+
```{eval-rst}
154+
.. function:: numpy_quaddtype.LongDoubleQuadPrecision(value)
155+
156+
Create a QuadPrecision scalar using the longdouble backend.
157+
158+
Equivalent to ``QuadPrecision(value, backend="longdouble")``.
159+
160+
:param value: Value to convert to quad precision.
161+
:return: Quad precision scalar using longdouble backend.
162+
:rtype: QuadPrecision
163+
```
164+
165+
```{eval-rst}
166+
.. function:: numpy_quaddtype.SleefQuadPrecDType()
167+
168+
Create a QuadPrecDType using the SLEEF backend.
169+
170+
Equivalent to ``QuadPrecDType(backend="sleef")``.
171+
172+
:return: Dtype for SLEEF-backed quad precision arrays.
173+
:rtype: QuadPrecDType
174+
```
175+
176+
```{eval-rst}
177+
.. function:: numpy_quaddtype.LongDoubleQuadPrecDType()
178+
179+
Create a QuadPrecDType using the longdouble backend.
180+
181+
Equivalent to ``QuadPrecDType(backend="longdouble")``.
182+
183+
:return: Dtype for longdouble-backed quad precision arrays.
184+
:rtype: QuadPrecDType
185+
```

0 commit comments

Comments
 (0)