pim/pg-rad
1
0
Fork 0
mirror of https://github.com/pim-n/pg-rad synced 2026-02-02 14:33:09 +01:00
Code Issues Packages Projects Releases Wiki Activity

improve docstrings for future comptability with mkdocs

Browse Source
This commit is contained in:
Pim Nelissen
2026-01-28 08:43:07 +01:00
parent f9ff50f4ef
commit d162f9fee3
4 changed files with 57 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
src/pg_rad/isotope.py
View File

@ -1,18 +1,17 @@
class Isotope:
"""Represents the essential information of an isotope.
Args:
name (str): Full name (e.g. Caesium-137).
E (float): Energy of the primary gamma in keV.
b (float): Branching ratio for the gamma at energy E.
"""
def __init__(
self,
name: str,
E: float,
b: float
):
"""_Represents the essential information of an isotope._
Args:
name (str): Full name (e.g. Caesium-137).
E (float): Energy of the primary gamma in keV.
b (float): Branching ratio for the gamma at energy E.
"""
if E <= 0:
raise ValueError("primary_gamma must be a positive energy (keV).")

37
src/pg_rad/landscape.py
View File

@ -6,20 +6,19 @@ from pg_rad.path import Path
from pg_rad.objects import Source
class Landscape:
"""A generic Landscape that can contain a Path and sources.
Args:
air_density (float, optional): Air density in kg / m^3. Defaults to 1.243.
size (int | tuple[int, int, int], optional): Size of the world. Defaults to 500.
scale (str, optional): The scale of the size argument passed. Defaults to 'meters'.
"""
def __init__(
self,
air_density: float = 1.243,
size: int | tuple[int, int, int] = 500,
scale = 'meters',
):
"""_A generic Landscape that can contain a Path and sources._
Args:
air_density (float, optional): Air density in kg / m^3. Defaults to 1.243.
size (int | tuple[int, int, int], optional): Size of the world. Defaults to 500.
scale (str, optional): The scale of the size argument passed. Defaults to 'meters'.
"""
if isinstance(size, int):
self.world = np.zeros((size, size, size))
elif isinstance(size, tuple) and len(size) == 3:
@ -34,7 +33,7 @@ class Landscape:
self.sources: list[Source] = []
def plot(self, z = 0):
"""_Plot a slice of the world at a height z._
"""Plot a slice of the world at a height `z`.
Args:
z (int, optional): Height of slice. Defaults to 0.
@ -78,7 +77,14 @@ class Landscape:
return fig, ax
def add_sources(self, *sources: Source):
"""Add one or more point sources to the world."""
"""Add one or more point sources to the world.
Args:
*sources (pg_rad.objects.Source): One or more sources, passed as
Source1, Source2, ...
Raises:
ValueError: If the source is outside the boundaries of the landscape.
"""
max_x, max_y, max_z = self.world.shape[:3]
@ -88,23 +94,26 @@ class Landscape:
0 <= source.z < max_z)
for source in sources
):
raise ValueError("One or more sources are outside the world boundaries.")
raise ValueError("One or more sources are outside the landscape!")
self.sources.extend(sources)
def set_path(self, path: Path):
"""
Set the path in the landscape.
"""
self.path = path
def create_landscape_from_path(path: Path, max_z = 500):
"""_Generate a Landscape from a path, using its dimensions to determine
the size of the Landscape._
"""Generate a landscape from a path, using its dimensions to determine
the size of the landscape.
Args:
path (Path): A Path object describing the trajectory.
max_z (int, optional): Height of the world. Defaults to 500 meters.
Returns:
Landscape: A Landscape with dimensions based on the provided Path.
landscape (pg_rad.landscape.Landscape): A landscape with dimensions based on the provided Path.
"""
max_x = np.ceil(max(path.x_list))
max_y = np.ceil(max(path.y_list))

13
src/pg_rad/objects.py
View File

@ -11,6 +11,16 @@ class Object:
z: float,
name: str = "Unnamed object",
color: str = 'grey'):
"""
A generic object.
Args:
x (float): X coordinate.
y (float): Y coordinate.
z (float): Z coordinate.
name (str, optional): Name for the object. Defaults to "Unnamed object".
color (str, optional): Matplotlib compatible color string. Defaults to "red".
"""
self.x = x
self.y = y
@ -35,7 +45,7 @@ class Source(Object):
isotope: Isotope,
name: str | None = None,
color: str = "red"):
"""_A point source._
"""A point source.
Args:
x (float): X coordinate.
@ -48,6 +58,7 @@ class Source(Object):
(Source-1, Source-2, etc.).
color (str, optional): Matplotlib compatible color string. Defaults to "red".
"""
self.id = Source._id_counter
Source._id_counter += 1

22
src/pg_rad/path.py
View File

@ -13,11 +13,11 @@ logger = setup_logger(__name__)
class PathSegment:
def __init__(self, a: tuple[float, float], b: tuple[float, float]):
"""_A straight Segment of a Path, from (x_a, y_a) to (x_b, y_b)._
"""A straight Segment of a Path, from (x_a, y_a) to (x_b, y_b).
Args:
a (tuple[float, float]): _The starting point (x_a, y_a)._
b (tuple[float, float]): _The final point (x_b, y_b)._
a (tuple[float, float]): The starting point (x_a, y_a).
b (tuple[float, float]): The final point (x_b, y_b).
"""
self.a = a
self.b = b
@ -45,7 +45,7 @@ class Path:
z: float = 0,
simplify_path = False
):
"""_Construct a path of sequences based on a list of coordinates._
"""Construct a path of sequences based on a list of coordinates.
Args:
coord_list (Sequence[tuple[float, float]]): List of x,y coordinates.
@ -95,7 +95,7 @@ def piecewise_regression_on_path(
keep_endpoints_equal: bool = False,
n_breakpoints: int = 3
):
"""_Take a Path object and return a piece-wise linear approximated Path._
"""From full resolution x and y arrays, return a piecewise linearly approximated/simplified pair of x and y arrays.
This function uses the `piecewise_regression` package. From a full set of
coordinate pairs, the function fits linear sections, automatically finding
@ -119,8 +119,11 @@ def piecewise_regression_on_path(
n_breakpoints (int, optional): Number of breakpoints. Defaults to 3.
Returns:
x (Sequence[float]): _Reduced list of x coordinates._
y (Sequence[float]): _Reduced list of y coordinates._
x (list[float]): Reduced list of x coordinates.
y (list[float]): Reduced list of y coordinates.
Raises:
ConvergenceError: If the fitting algorithm failed to simplify the path.
Reference:
Pilgrim, C., (2021). piecewise-regression (aka segmented regression) in Python. Journal of Open Source Software, 6(68), 3859, https://doi.org/10.21105/joss.03859.
@ -163,11 +166,10 @@ def path_from_RT90(
north_col: str = "North",
**kwargs
) -> Path:
"""_Construct a path from East and North formatted coordinates (RT90) in a Pandas DataFrame._
"""Construct a path from East and North formatted coordinates (RT90) in a Pandas DataFrame.
Args:
df (pd.DataFrame): DataFrame containing at least the two columns noted in the cols argument.
df (pandas.DataFrame): DataFrame containing at least the two columns noted in the cols argument.
east_col (str): The column name for the East coordinates.
north_col (str): The column name for the North coordinates.