Add documentation for types: scalars, lists, and NumPy arrays by PiotrPich2024 · Pull Request #81 · libamtrack/libamtrack.github.io

PiotrPich2024 · 2026-03-13T18:07:52Z

Added documentation about passed types and how they are converted into C variables.
Added warning inside documentation about passing wrong precision floating-point types numbers.

grzanka

see comments

grzanka

see comments

Copilot

Pull request overview

This PR updates the libamtrack documentation site to better describe Python↔C type conversions for the pyamtrack wrapper, and fixes the top-level README link to the hosted docs site.

Changes:

Fix README link to use the canonical https://libamtrack.github.io URL.
Add a new docs/python/types.md page documenting Python input/output conversions (scalars, lists, NumPy arrays) for fully ported functions.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
README.md	Fixes documentation site link to include the `https://` scheme.
docs/python/types.md	Adds a type conversion reference page for key `pyamtrack` functions/modules.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…umPy arrays

… examples for special floating values and np.float64 support

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

…prove clarity of input types for electron_range function

…scriptions

…ove code examples for clarity and consistency in types.md

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 12 comments.

Comments suppressed due to low confidence (4)

docs/python/types.md:29

Grammar and wording issues in the array-like notes: “tuple and set is” should be plural, the inline “NOT IMPLEMENTED YET” is distracting, and “0-d python lists” isn’t a meaningful concept (lists are 1-D). Consider clarifying this as “empty Python lists” and “0‑D NumPy arrays”.

**Note:** `tuple` and `set` is not treated as array-like and will usually raise a `TypeError`. `NOT IMPLEMENTED YET`

**Note:** `0-d numpy.ndarray` and `0-d python lists` are treated as arrays-like type not scalars

docs/python/types.md:104

This list example both uses the undocumented E_MeV keyword and claims the output is a numpy.ndarray. Elsewhere in this docs set (e.g. docs/python/API/stopping/electron_range.md and docs/python/API/converters.md) list inputs are documented as returning Python lists. Please align this example with the established API docs to avoid confusing users.

E_MeV = [50.0, 100.0, 150.0]
range_m = pyamtrack.stopping.electron_range(E_MeV = E_MeV)
# E_MeV -> [50.0, 100.0, 150.0] MeV
# range_m -> numpy.ndarray([0.2537, 0.4245, 0.5689])  (shape (3,), dtype float64)
# range_m[i] corresponds to E_MeV[i], same order preserved

docs/python/types.md:207

This example again uses E_MeV= / material_id= / model_id= and describes a np.ndarray output for a list input. That contradicts the existing API docs in this repo, which document list inputs as returning Python lists (e.g. docs/python/API/stopping/electron_range.md, docs/python/API/converters.md). Please align the example and expected return type with the established documentation.

E_MeV = [50.0, 100.0]
range_m = pyamtrack.stopping.electron_range(E_MeV = E_MeV, material_id = 1, model_id = 7)
# material_id=1 and model_id=7 stay scalar -> broadcast to match E_MeV's length
# range_m -> np.ndarray([0.2537, 0.4245])  (shape=(2,), dtype=float64)

**docs/python/types.md:232**
* After switching the example to list inputs, the return type in this comment should be a Python list (as documented elsewhere in this repo for list inputs), not `np.ndarray`.

range_m -> np.ndarray([0.2537, 0.4245, 0.5689])

</details>

+import pyamtrack.stopping as s
+
+range_m = s.electron_range(E_MeV = float("nan"))
+# float("nan) -> NaN (undefined)


+import pyamtrack.stopping as s
+
+range_m = s.electron_range(E_MeV = -1 / float('inf'))
+# -1 / x_MeV -> -0.0


+range_m = s.electron_range(E_MeV = 50.0)
+# E_MeV = 50.0 (float) -> range_m = 0.2537 (float)


+range_m = s.electron_range(E_MeV = 1)
+# E_MeV = 1 (int, promoted to double internally) -> range_m = 0.0044 (float)


+range_m = s.electron_range(E_MeV = np.float64(50.0))
+# E_MeV = 50.0 (np.float64) -> range_m = 0.2537 (Python float, NOT np.float64)


+range_m = pyamtrack.stopping.electron_range(E_MeV = 100.0, material_id = 1, model_id = 7)
+# range_m -> 0.4245 (Python float)


+E_MeV = [50.0, 100.0, 150.0]
+range_m = pyamtrack.stopping.electron_range(E_MeV = E_MeV, material_id = 1, model_id = 7)


+# material_id=1, model_id=7 broadcast internally to:
+#   material_id = [1, 1, 1], model_id = [7, 7, 7]
+# equivalent to:
+#   electron_range(E_MeV=50.0,  material_id=1, model_id=7)
+#   electron_range(E_MeV=100.0, material_id=1, model_id=7)
+#   electron_range(E_MeV=150.0, material_id=1, model_id=7)


+```python
+import pyamtrack.stopping as s
+
+range_m = s.electron_range(E_MeV = float("nan"))


+```python
+import pyamtrack.stopping as s
+
+range_m = s.electron_range(E_MeV = -1 / float('inf'))


…ts and enhancing example consistency

Add documentation for types: scalars, lists, and NumPy arrays

ffd5d16

grzanka assigned PiotrPich2024 Mar 13, 2026

grzanka reviewed Mar 13, 2026

View reviewed changes