Add documentation for types: scalars, lists, and NumPy arrays#81
Open
PiotrPich2024 wants to merge 7 commits into
Open
Add documentation for types: scalars, lists, and NumPy arrays#81PiotrPich2024 wants to merge 7 commits into
PiotrPich2024 wants to merge 7 commits into
Conversation
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
grzanka
reviewed
Mar 13, 2026
Contributor
There was a problem hiding this comment.
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.ioURL. - Add a new
docs/python/types.mdpage 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.
Comment on lines
+5
to
+8
| # Type Conversion Tables for Ported Functions | ||
|
|
||
| This page shows input/output type conversions for all fully ported functions in pyamtrack. | ||
|
|
| | Python Input | → C Input | → C Output | → Python Output | | ||
| |---|---|---|---| | ||
| | `float` (energy in MeV) | `double` | `double` | `float` | | ||
| | `list` of floats | `double*` array | `double*` array | `np.ndarray` (float64) | |
Comment on lines
+43
to
+44
| | `list` of floats | `double*` array | `double*` array | `np.ndarray` (float64) | | ||
| | `np.ndarray` (float64) | `double*` array | `double*` array | `np.ndarray` (float64) | |
Comment on lines
+65
to
+69
| | Python Input | → C Input | → C Output | → Python Output | | ||
| |---|---|---|---| | ||
| | `float` (energy in MeV) | `double` | `double` | `float` | | ||
| | `list` of floats | `double*` array | `double*` array | `np.ndarray` (float64) | | ||
| | `np.ndarray` (float64) | `double*` array | `double*` array | `np.ndarray` (float64) | |
Comment on lines
+79
to
+83
| range_cm = pyamtrack.stopping.electron_range(150.0, material=1, model="tabata") | ||
|
|
||
| # Array (recommended for plots) | ||
| energies = np.linspace(10.0, 1000.0, 500, dtype=np.float64) | ||
| ranges = pyamtrack.stopping.electron_range(energies, material=1, model="tabata") |
Comment on lines
+103
to
+107
| # Query material property | ||
| density = pyamtrack.materials.get_density(1) # material ID 1 | ||
|
|
||
| # List available materials | ||
| materials = pyamtrack.materials.list_materials() |
… examples for special floating values and np.float64 support
| @@ -0,0 +1,258 @@ | |||
| # pyamtrack — input types and vectorization behavior | |||
|
|
||
| This document describes which Python/NumPy types are accepted by `pyamtrack` functions and how `pyamtrack` interprets inputs (scalars, lists, `numpy.ndarray`) and what types it returns. | ||
|
|
||
| It specifically covers functions exported by modules (e.g. `pyamtrack.stopping`, `pyamtrack.converters`) that use the shared C++ wrappers in `src/wrapper/`. |
Comment on lines
+24
to
+26
| **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 |
| In `pyamtrack`, a scalar is a Python object of type: | ||
| - `float` | ||
| - `int` | ||
| - `np.float64/32` |
| Most commonly accepted types are: | ||
| - `float` | ||
| - `int` | ||
| - `np.float64/32` |
|
|
||
| Many functions also work with mixed numeric elements inside lists (e.g. `[1, 2.0, 3]`), but this depends on the conversion path. | ||
|
|
||
| If an argument is not `float`, `int`, `list`, or `numpy.ndarray`, a type error will be raised. |
Comment on lines
+37
to
+41
| # returns nan | ||
| s.electron_range(x*0) | ||
|
|
||
| #return 0.0 | ||
| s.electron_range(-1/x) |
…prove clarity of input types for electron_range function
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.