osiris-utils 1.1.10a0__py3-none-any.whl → 1.2.0__py3-none-any.whl

osiris_utils/cli/__main__.py

@@ -0,0 +1,85 @@
+"""Command-line interface for osiris_utils."""
+
+import argparse
+import sys
+
+import osiris_utils
+
+from . import export, info, plot, validate
+
+__version__ = osiris_utils.__version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for the osiris CLI.
+
+    Parameters
+    ----------
+    argv : list of str, optional
+        Command line arguments. If None, uses sys.argv[1:].
+
+    Returns
+    -------
+    int
+        Exit code (0 for success, non-zero for errors).
+
+    """
+    parser = argparse.ArgumentParser(
+        prog="osiris",
+        description="Command-line tools for OSIRIS plasma simulation data analysis",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  osiris info path/to/simulation          # Show simulation metadata
+  osiris export file.h5 --format csv      # Export data to CSV
+  osiris plot file.h5 --save plot.png     # Create quick plot
+  osiris validate path/to/simulation      # Check file integrity
+
+For help on a specific command:
+  osiris <command> --help
+        """,
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"osiris_utils {__version__}",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose output",
+    )
+
+    # Create subparsers for different commands
+    subparsers = parser.add_subparsers(
+        title="commands",
+        dest="command",
+        help="Available commands",
+        required=True,
+    )
+
+    # Import command modules
+
+    # Register each command's parser
+    info.register_parser(subparsers)
+    export.register_parser(subparsers)
+    plot.register_parser(subparsers)
+    validate.register_parser(subparsers)
+
+    # Parse arguments
+    args = parser.parse_args(argv)
+
+    # Execute the appropriate command
+    try:
+        return args.func(args)
+    except Exception:
+        if args.verbose:
+            raise
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

osiris_utils/cli/export.py

@@ -0,0 +1,199 @@
+"""Export command - convert OSIRIS data to different formats."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+import osiris_utils as ou
+
+
+def register_parser(subparsers) -> None:
+    """Register the 'export' subcommand parser."""
+    parser = subparsers.add_parser(
+        "export",
+        help="Export OSIRIS data to CSV, JSON, or NumPy formats",
+        description="Convert OSIRIS HDF5 data to common formats for analysis",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  osiris export file.h5 --format csv --output data.csv
+  osiris export sim/MS/FLD/e3 --format npy --output e3_data.npy
+  osiris export file.h5 --format json --output data.json
+        """,
+    )
+
+    parser.add_argument(
+        "path",
+        type=str,
+        help="Path to OSIRIS file or diagnostic directory",
+    )
+
+    parser.add_argument(
+        "-f",
+        "--format",
+        type=str,
+        choices=["csv", "json", "npy"],
+        default="csv",
+        help="Output format (default: csv)",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        required=True,
+        help="Output file path",
+    )
+
+    parser.add_argument(
+        "-t",
+        "--timestep",
+        type=int,
+        default=None,
+        help="Specific timestep index to export (default: export all)",
+    )
+
+    parser.add_argument(
+        "--no-coords",
+        action="store_true",
+        help="Exclude coordinate information (data only)",
+    )
+
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    """Execute the export command."""
+    path = Path(args.path)
+
+    if not path.exists():
+        print(f"Error: Path '{path}' does not exist", file=sys.stderr)
+        return 1
+
+    try:
+        # Load data
+        if path.is_file():
+            data_obj = ou.OsirisGridFile(str(path))
+            export_single_file(data_obj, args)
+        elif path.is_dir():
+            # Assume it's a diagnostic directory
+            export_diagnostic_dir(path, args)
+        else:
+            print(f"Error: '{path}' is not a file or directory", file=sys.stderr)
+            return 1
+
+        print(f"Exported to: {args.output}")
+        return 0
+
+    except Exception as e:
+        print(f"Error exporting data: {e}", file=sys.stderr)
+        return 1
+
+
+def export_single_file(data_obj, args: argparse.Namespace) -> None:
+    """Export a single OSIRIS file."""
+    data = data_obj.data
+    output_path = Path(args.output)
+
+    if args.format == "csv":
+        export_to_csv(data, data_obj, output_path, args.no_coords)
+    elif args.format == "json":
+        export_to_json(data, data_obj, output_path, args.no_coords)
+    elif args.format == "npy":
+        np.save(output_path, data)
+
+
+def export_diagnostic_dir(diag_path: Path, args: argparse.Namespace) -> None:
+    """Export all timesteps from a diagnostic directory."""
+    # Find all h5 files
+    h5_files = sorted(list(diag_path.glob("*.h5")))
+
+    if not h5_files:
+        raise ValueError(f"No HDF5 files found in {diag_path}")
+
+    if args.timestep is not None:
+        # Export specific timestep
+        if args.timestep >= len(h5_files):
+            raise ValueError(f"Timestep {args.timestep} out of range (0-{len(h5_files) - 1})")
+        data_obj = ou.OsirisGridFile(str(h5_files[args.timestep]))
+        export_single_file(data_obj, args)
+    # Export all timesteps
+    elif args.format == "npy":
+        # Stack all data into single array
+        all_data = []
+        for f in h5_files:
+            data_obj = ou.OsirisGridFile(str(f))
+            all_data.append(data_obj.data)
+        stacked = np.array(all_data)
+        np.save(args.output, stacked)
+    else:
+        # For CSV/JSON, export each timestep separately or create multi-index
+        export_multi_timestep(h5_files, args)
+
+
+def export_to_csv(data: np.ndarray, data_obj, output_path: Path, no_coords: bool) -> None:
+    """Export data to CSV format."""
+    if data.ndim == 1:
+        # 1D data
+        if no_coords:
+            df = pd.DataFrame({data_obj.name: data})
+        else:
+            df = pd.DataFrame({"x": data_obj.x[0], data_obj.name: data})
+    elif data.ndim == 2:
+        # 2D data - flatten with coordinates
+        if no_coords:
+            df = pd.DataFrame(data)
+        else:
+            x = data_obj.x[0]
+            y = data_obj.x[1]
+            xx, yy = np.meshgrid(x, y, indexing="ij")
+            df = pd.DataFrame({"x": xx.flatten(), "y": yy.flatten(), data_obj.name: data.flatten()})
+    else:
+        # 3D+ data - just flatten
+        df = pd.DataFrame(data.flatten(), columns=[data_obj.name])
+
+    df.to_csv(output_path, index=False)
+
+
+def export_to_json(data: np.ndarray, data_obj, output_path: Path, no_coords: bool) -> None:
+    """Export data to JSON format."""
+    output = {
+        "name": data_obj.name,
+        "type": data_obj.type,
+        "units": data_obj.units,
+        "time": data_obj.time,
+        "iteration": data_obj.iter,
+        "data": data.tolist(),
+    }
+
+    if not no_coords:
+        output["grid"] = {f"x{i + 1}": coord.tolist() for i, coord in enumerate(data_obj.x)}
+        output["axis_info"] = data_obj.axis
+
+    with open(output_path, "w") as f:
+        json.dump(output, f, indent=2)
+
+
+def export_multi_timestep(h5_files: list, args: argparse.Namespace) -> None:
+    """Export multiple timesteps to CSV/JSON."""
+    if args.format == "csv":
+        # Create multi-index CSV
+        all_dfs = []
+        for i, f in enumerate(h5_files):
+            data_obj = ou.OsirisGridFile(str(f))
+            df = pd.DataFrame({"timestep": i, "time": data_obj.time, "data": data_obj.data.flatten()})
+            all_dfs.append(df)
+        combined = pd.concat(all_dfs, ignore_index=True)
+        combined.to_csv(args.output, index=False)
+    elif args.format == "json":
+        # Create JSON array
+        all_data = []
+        for f in h5_files:
+            data_obj = ou.OsirisGridFile(str(f))
+            all_data.append({"time": data_obj.time, "iteration": data_obj.iter, "data": data_obj.data.tolist()})
+        with open(args.output, "w") as outf:
+            json.dump(all_data, outf, indent=2)

osiris_utils/cli/info.py

@@ -0,0 +1,156 @@
+"""Info command - display metadata about OSIRIS files and simulations."""
+
+import argparse
+import sys
+from pathlib import Path
+
+import osiris_utils as ou
+
+
+def register_parser(subparsers) -> None:
+    """Register the 'info' subcommand parser."""
+    parser = subparsers.add_parser(
+        "info",
+        help="Display metadata about OSIRIS files or simulations",
+        description="Show detailed information about OSIRIS simulation data",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  osiris info path/to/simulation          # Show all simulation info
+  osiris info path/to/file.h5             # Show single file info
+  osiris info path/to/simulation --brief  # Show summary only
+        """,
+    )
+
+    parser.add_argument(
+        "path",
+        type=str,
+        help="Path to OSIRIS simulation directory or HDF5 file",
+    )
+
+    parser.add_argument(
+        "--brief",
+        action="store_true",
+        help="Show brief summary only",
+    )
+
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    """Execute the info command."""
+    path = Path(args.path)
+
+    if not path.exists():
+        print(f"Error: Path '{path}' does not exist", file=sys.stderr)
+        return 1
+
+    # Determine if path is a file or directory
+    # Determine if path is a file or directory
+    if path.is_file():
+        return show_file_info(path, args.brief)
+    elif path.is_dir():
+        return show_simulation_info(path, args.brief, args.verbose)
+    else:
+        print(f"Error: '{path}' is not a file or directory", file=sys.stderr)
+        return 1
+
+
+def show_file_info(filepath: Path, brief: bool = False) -> int:
+    """Display information about a single OSIRIS file."""
+    try:
+        # Try to open as grid file
+        data = ou.OsirisGridFile(str(filepath))
+
+        print(f"File: {filepath.name}")
+        print(f"Type: {data.type}")
+        print(f"Name: {data.name}")
+        print(f"Dimensions: {data.dim}D")
+
+        if not brief:
+            print("\nGrid Information:")
+            print(f"  nx: {data.nx}")
+            print(f"  dx: {data.dx}")
+            print(f"  Grid range: {[tuple(ax['axis']) for ax in data.axis]}")
+
+            print("\nTime Information:")
+            print(f"  Time: {data.time}")
+            print(f"  dt: {data.dt}")
+            print(f"  Iteration: {data.iter}")
+
+            print("\nData Information:")
+            print(f"  Shape: {data.data.shape}")
+            print(f"  Units: {data.units}")
+            print(f"  Label: {data.label}")
+
+        return 0
+
+    except Exception as e:
+        print(f"Error reading file: {e}", file=sys.stderr)
+        return 1
+
+
+def show_simulation_info(simpath: Path, brief: bool = False, verbose: bool = False) -> int:
+    """Display information about an OSIRIS simulation."""
+    try:
+        # Look for input deck
+        input_deck = None
+        for candidate in ["os-stdin", "input.deck", "deck.in"]:
+            deck_path = simpath / candidate
+            if deck_path.exists():
+                input_deck = deck_path
+                break
+
+        if input_deck is None:
+            print(f"Error: No input deck found in {simpath}", file=sys.stderr)
+            print("  (Looking for: os-stdin, input.deck, deck.in)", file=sys.stderr)
+            return 1
+
+        # Load simulation
+        sim = ou.Simulation(str(input_deck))
+
+        print(f"Simulation: {simpath.name}")
+        print(f"Input Deck: {input_deck.name}")
+
+        if not brief:
+            print("\nSpecies:")
+            for species in sim.species:
+                print(f"  - {species}")
+
+            # Scan for available diagnostics
+            print("\nAvailable Diagnostics:")
+            ms_path = simpath / "MS"
+            if ms_path.exists():
+                # Check for fields
+                fld_path = ms_path / "FLD"
+                if fld_path.exists():
+                    print("  Fields:")
+                    for item in sorted(fld_path.iterdir()):
+                        if item.is_dir():
+                            # Count files in diagnostic
+                            n_files = len(list(item.glob("*.h5")))
+                            print(f"    - {item.name} ({n_files} timesteps)")
+
+                # Check for density/current
+                for diag_type in ["DENSITY", "CURRENT"]:
+                    diag_path = ms_path / diag_type
+                    if diag_path.exists():
+                        print(f"  {diag_type.title()}:")
+                        for species_dir in sorted(diag_path.iterdir()):
+                            if species_dir.is_dir():
+                                for qty_dir in sorted(species_dir.iterdir()):
+                                    if qty_dir.is_dir():
+                                        n_files = len(list(qty_dir.glob("*.h5")))
+                                        print(f"    - {species_dir.name}/{qty_dir.name} ({n_files} timesteps)")
+
+        return 0
+
+    except Exception as e:
+        print(f"Error reading simulation: {e}", file=sys.stderr)
+        if verbose:
+            raise
+        return 1
+
+
+# Make args available in scope for error handling
+args = None

osiris_utils/cli/plot.py

@@ -0,0 +1,189 @@
+"""Plot command - quick visualization of OSIRIS data."""
+
+import argparse
+import sys
+from pathlib import Path
+
+import matplotlib
+import matplotlib.pyplot as plt
+import numpy as np
+
+import osiris_utils as ou
+
+# Use non-interactive backend by default for CLI
+matplotlib.use('Agg')
+
+
+def register_parser(subparsers) -> None:
+    """Register the 'plot' subcommand parser."""
+    parser = subparsers.add_parser(
+        "plot",
+        help="Create quick plots from OSIRIS data",
+        description="Generate publication-quality plots from OSIRIS simulation data",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  osiris plot file.h5 --save plot.png
+  osiris plot file.h5 --save plot.png --title "Ez Field"
+  osiris plot file.h5 --save plot.png --cmap viridis
+  osiris plot file.h5 --display  # Show interactive plot
+        """,
+    )
+
+    parser.add_argument(
+        "path",
+        type=str,
+        help="Path to OSIRIS HDF5 file",
+    )
+
+    parser.add_argument(
+        "-s",
+        "--save",
+        type=str,
+        default=None,
+        help="Save plot to file (e.g., plot.png)",
+    )
+
+    parser.add_argument(
+        "--display",
+        action="store_true",
+        help="Display plot interactively (requires X server)",
+    )
+
+    parser.add_argument(
+        "--title",
+        type=str,
+        default=None,
+        help="Plot title (default: auto-generated)",
+    )
+
+    parser.add_argument(
+        "--cmap",
+        type=str,
+        default="RdBu_r",
+        help="Colormap for 2D plots (default: RdBu_r)",
+    )
+
+    parser.add_argument(
+        "--dpi",
+        type=int,
+        default=150,
+        help="DPI for saved plots (default: 150)",
+    )
+
+    parser.add_argument(
+        "--log-scale",
+        action="store_true",
+        help="Use logarithmic scale for color/y-axis",
+    )
+
+    parser.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    """Execute the plot command."""
+    path = Path(args.path)
+
+    if not path.exists():
+        print(f"Error: File '{path}' does not exist", file=sys.stderr)
+        return 1
+
+    if not path.is_file():
+        print(f"Error: '{path}' is not a file", file=sys.stderr)
+        return 1
+
+    if not args.save and not args.display:
+        print("Error: Must specify --save or --display", file=sys.stderr)
+        return 1
+
+    try:
+        # Switch to interactive backend if displaying
+        if args.display:
+            matplotlib.use('TkAgg')
+
+        # Load data
+        data_obj = ou.OsirisGridFile(str(path))
+
+        # Create plot based on dimensionality
+        if data_obj.dim == 1:
+            create_1d_plot(data_obj, args)
+        elif data_obj.dim == 2:
+            create_2d_plot(data_obj, args)
+        else:
+            print(f"Error: {data_obj.dim}D plotting not supported yet", file=sys.stderr)
+            return 1
+
+        # Save or display
+        if args.save:
+            plt.savefig(args.save, dpi=args.dpi, bbox_inches='tight')
+            print(f"Plot saved to: {args.save}")
+
+        if args.display:
+            plt.show()
+
+        return 0
+
+    except Exception as e:
+        print(f"Error creating plot: {e}", file=sys.stderr)
+        return 1
+
+
+def create_1d_plot(data_obj, args: argparse.Namespace) -> None:
+    """Create a 1D line plot."""
+    fig, ax = plt.subplots(figsize=(10, 6))
+
+    # For 1D data, x is the coordinate array directly
+    x = data_obj.x
+    data = data_obj.data
+
+    ax.plot(x, data, linewidth=2)
+
+    # Labels
+    if args.title:
+        ax.set_title(args.title)
+    else:
+        ax.set_title(f"${data_obj.label}$ at t = {data_obj.time}")
+
+    ax.set_xlabel(data_obj.axis[0].get('plot_label', f'x [{data_obj.axis[0]["units"]}]'))
+    ax.set_ylabel(f"${data_obj.label}$ [{data_obj.units}]")
+
+    if args.log_scale:
+        ax.set_yscale('log')
+
+    ax.grid(True, alpha=0.3)
+    plt.tight_layout()
+
+
+def create_2d_plot(data_obj, args: argparse.Namespace) -> None:
+    """Create a 2D heatmap."""
+    fig, ax = plt.subplots(figsize=(10, 8))
+
+    x = data_obj.x[0]
+    y = data_obj.x[1]
+    data = data_obj.data
+
+    # Create meshgrid for pcolormesh
+    extent = [x[0], x[-1], y[0], y[-1]]
+
+    if args.log_scale:
+        # Use symmetric log scale for data that may have negative values
+        vmax = np.abs(data).max()
+        norm = matplotlib.colors.SymLogNorm(linthresh=vmax / 100, vmin=-vmax, vmax=vmax)
+        im = ax.imshow(data.T, origin='lower', aspect='auto', extent=extent, cmap=args.cmap, norm=norm)
+    else:
+        im = ax.imshow(data.T, origin='lower', aspect='auto', extent=extent, cmap=args.cmap)
+
+    # Colorbar
+    cbar = plt.colorbar(im, ax=ax)
+    cbar.set_label(f"${data_obj.label}$ [{data_obj.units}]")
+
+    # Labels
+    if args.title:
+        ax.set_title(args.title)
+    else:
+        ax.set_title(f"${data_obj.label}$ at t = {data_obj.time}")
+
+    ax.set_xlabel(data_obj.axis[0].get('plot_label', f'x [{data_obj.axis[0]["units"]}]'))
+    ax.set_ylabel(data_obj.axis[1].get('plot_label', f'y [{data_obj.axis[1]["units"]}]'))
+
+    plt.tight_layout()