schr.utils.paths module

Path utilities for managing output directories and files.

This module provides functions for generating standardized paths for simulation results, ensuring they are saved to the user’s ~/.schr directory.

schr.utils.paths.clean_old_simulations(keep_recent: int = 10) → list[Path]

Clean old simulation directories, keeping only the most recent ones.

Parameters:

keep_recent – Number of recent simulations to keep (default: 10).

Returns:

List of paths that were removed.

Example

>>> removed = clean_old_simulations(keep_recent=5)
>>> print(f"Removed {len(removed)} old simulations")
Removed 3 old simulations

schr.utils.paths.get_cache_dir(create: bool = True) → Path

Get directory for cached computations.

Parameters:

create – If True, create the directory if it doesn’t exist (default: True).

Returns:

Path to ~/.schr/cache directory.

Example

>>> cache_dir = get_cache_dir()
>>> print(cache_dir)
/Users/username/.schr/cache

schr.utils.paths.get_data_dir(create: bool = True) → Path

Get directory for data files (potentials, initial conditions, etc.).

Parameters:

create – If True, create the directory if it doesn’t exist (default: True).

Returns:

Path to ~/.schr/data directory.

Example

>>> data_dir = get_data_dir()
>>> print(data_dir)
/Users/username/.schr/data

schr.utils.paths.get_output_dir(simulation_name: str, create: bool = True) → Path

Get output directory for a simulation.

Creates a subdirectory in ~/.schr for the simulation results.

Parameters:

• simulation_name – Name of the simulation (e.g., “double_slit”, “tunneling”).

• create – If True, create the directory if it doesn’t exist (default: True).

Returns:

Path to the simulation output directory.

Example

>>> output_dir = get_output_dir("double_slit")
>>> print(output_dir)
/Users/username/.schr/double_slit

schr.utils.paths.get_output_path(simulation_name: str, filename: str, timestamp: bool = True, create_dir: bool = True) → Path

Get full path for an output file.

Parameters:

• simulation_name – Name of the simulation.

• filename – Name of the output file (e.g., “animation.mp4”, “final_state.npy”).

• timestamp – If True, append timestamp to filename suffix (default: True).

• create_dir – If True, create the directory if needed (default: True).

Returns:

Full path to the output file.

Example

>>> path = get_output_path("double_slit", "animation.mp4")
>>> print(path)
/Users/username/.schr/double_slit/animation_20251104_153022.mp4

>>> path = get_output_path("double_slit", "animation.mp4", timestamp=False)
>>> print(path)
/Users/username/.schr/double_slit/animation.mp4

schr.utils.paths.get_schr_home() → Path

Get the Schr home directory (~/.schr).

Creates the directory if it doesn’t exist.

Returns:

Path to ~/.schr directory.

Example

>>> home = get_schr_home()
>>> print(home)
/Users/username/.schr

schr.utils.paths.get_simulation_info(simulation_dir: Path) → dict

Get information about a simulation directory.

Parameters:

simulation_dir – Path to the simulation directory.

Returns:

Dictionary with simulation information.

Example

>>> info = get_simulation_info(Path("~/.schr/double_slit"))
>>> print(info)
{
    'name': 'double_slit',
    'size_mb': 125.3,
    'num_files': 126,
    'created': '2025-11-04 15:30:22',
    'modified': '2025-11-04 15:35:45'
}

schr.utils.paths.list_simulations() → list[str]

List all simulation directories in ~/.schr.

Returns:

List of simulation directory names.

Example

>>> simulations = list_simulations()
>>> for sim in simulations:
...     print(sim)
double_slit
tunneling
quantum_vortex