utils

General utilities.

toric_spines_sim.utils

General-purpose utility functions for toric_spines_sim.

load_xyz_points(value)

Load XYZ coordinates from a whitespace-delimited file.

Each row must contain at least 3 values (x, y, z). Extra columns are ignored.

Parameters:

Name	Type	Description	Default
value	path - like	Path to the coordinate file.	required

Returns:

Type	Description
list of tuple of float	(x, y, z) rows.

Raises:

Type	Description
ValueError	If the file is empty or rows have fewer than 3 values.

Source code in toric_spines_sim/utils.py

def load_xyz_points(value: Union[str, Path]) -> List[Tuple[float, float, float]]:
    """Load XYZ coordinates from a whitespace-delimited file.

    Each row must contain at least 3 values (x, y, z). Extra columns are ignored.

    Parameters
    ----------
    value : path-like
        Path to the coordinate file.

    Returns
    -------
    list of tuple of float
        ``(x, y, z)`` rows.

    Raises
    ------
    ValueError
        If the file is empty or rows have fewer than 3 values.
    """
    arr = np.loadtxt(str(value))
    arr = np.asarray(arr, dtype=float)
    if arr.size == 0:
        raise ValueError("coordinate file is empty")
    if arr.ndim == 1:
        arr = arr.reshape(1, -1)
    if arr.shape[1] < 3:
        raise ValueError("each line must contain at least 3 values: x y z")
    pts: List[Tuple[float, float, float]] = []
    for row in arr:
        pts.append((float(row[0]), float(row[1]), float(row[2])))
    return pts

equal_vectors(v1, v2, tol=1e-06)

Return True if two vectors are equal within L2 tolerance tol.

Source code in toric_spines_sim/utils.py

def equal_vectors(v1: Sequence[float], v2: Sequence[float], tol: float = 1e-6) -> bool:
    """Return True if two vectors are equal within L2 tolerance ``tol``."""
    v1 = np.array(v1)
    v2 = np.array(v2)
    return bool(np.linalg.norm(v1 - v2) < tol)

join_tags_dsl(tags)

Build an Arbor region DSL expression for the union of multiple tags.

The DSL (join ...) operator accepts exactly two arguments, so multiple tags are combined via nested binary joins.

Parameters:

Name	Type	Description	Default
tags	Sequence[int]	One or more integer region tags.	required

Returns:

Type	Description
str	An s-expression string, e.g. "(join (tag 3) (tag 5))".

Raises:

Type	Description
ValueError	If tags is empty.

Examples:

>>> join_tags_dsl([3])
'(tag 3)'
>>> join_tags_dsl([3, 5, 6])
'(join (join (tag 3) (tag 5)) (tag 6))'

Source code in toric_spines_sim/utils.py

def join_tags_dsl(tags: Sequence[int]) -> str:
    """Build an Arbor region DSL expression for the union of multiple tags.

    The DSL ``(join ...)`` operator accepts exactly two arguments, so multiple
    tags are combined via nested binary joins.

    Parameters
    ----------
    tags : Sequence[int]
        One or more integer region tags.

    Returns
    -------
    str
        An s-expression string, e.g. ``"(join (tag 3) (tag 5))"``.

    Raises
    ------
    ValueError
        If *tags* is empty.

    Examples
    --------
    >>> join_tags_dsl([3])
    '(tag 3)'
    >>> join_tags_dsl([3, 5, 6])
    '(join (join (tag 3) (tag 5)) (tag 6))'
    """
    if len(tags) == 0:
        raise ValueError("tags must be non-empty")
    expr = f"(tag {tags[0]})"
    for tag in tags[1:]:
        expr = f"(join {expr} (tag {tag}))"
    return expr

read_nff_s_points(path, *, return_numpy=False)

Read all 's x y z i' points from an NFF file and return them in order.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	Path to the .nff file.	required
return_numpy	bool	If True, return an (N, 3) NumPy array of dtype float. Otherwise, return a Python list of (x, y, z) tuples.	False

Returns:

Type	Description
list[tuple[float, float, float]] | ndarray	The sequence of (x, y, z) triples extracted from the file (possibly empty if no 's' lines are present).

Source code in toric_spines_sim/utils.py

def read_nff_s_points(
    path: Union[str, Path], *, return_numpy: bool = False
) -> Union[List[Tuple[float, float, float]], np.ndarray]:
    """Read all 's x y z i' points from an NFF file and return them in order.

    Parameters
    ----------
    path
        Path to the .nff file.
    return_numpy
        If True, return an (N, 3) NumPy array of dtype float. Otherwise, return a
        Python list of (x, y, z) tuples.

    Returns
    -------
    list[tuple[float, float, float]] | np.ndarray
        The sequence of (x, y, z) triples extracted from the file (possibly empty
        if no 's' lines are present).
    """
    p = Path(path)
    with p.open("r", errors="ignore") as f:
        points = list(_iter_nff_s_points(f))
    if return_numpy:
        return np.asarray(points, dtype=float)
    return points

read_nff_points_and_write_txt_file(input_path, output_path)

Write NFF s points as a whitespace-delimited XYZ text file.

Source code in toric_spines_sim/utils.py

def read_nff_points_and_write_txt_file(
    input_path: Union[str, Path], output_path: Union[str, Path]
) -> None:
    """Write NFF ``s`` points as a whitespace-delimited XYZ text file."""
    points = read_nff_s_points(input_path)
    np.savetxt(output_path, points, fmt="%.3f")