Cycles-utils 4.0.2__tar.gz → 4.0.3__tar.gz

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/Cycles_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Cycles-utils
-Version: 4.0.2
+Version: 4.0.3
 Summary: Python scripts to build Cycles input files and post-process Cycles output files
 Home-page: https://github.com/PSUmodeling/Cycles-utils
 Author: Yuning Shi

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Cycles-utils
-Version: 4.0.2
+Version: 4.0.3
 Summary: Python scripts to build Cycles input files and post-process Cycles output files
 Home-page: https://github.com/PSUmodeling/Cycles-utils
 Author: Yuning Shi

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/__init__.py

@@ -12,6 +12,7 @@ from .cycles_tools import SoilLayer
 from .cycles_tools import plot_yield
 from .cycles_tools import plot_operations
 from .cycles_tools import plot_map
+from .cycles_tools import plot_satellite_map
 from .cycles_tools import Operation, Planting, Tillage, Harvest, Kill, FixedFertilization, FixedIrrigation, AutoIrrigation
 from .cycles_runner import CyclesRunner
 from .rotation_builder import CyclesRotationBuilder, Crop, CropGroup

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles.py

@@ -5,7 +5,6 @@ import pandas as pd
 import subprocess
 from collections.abc import Collection
 from dataclasses import dataclass, field
-from datetime import datetime
 from pathlib import Path
 from matplotlib.axes import Axes
 from .cycles_tools import SoilLayer, ControlConfig
@@ -27,8 +26,8 @@ class Output:
 class Cycles:
     """Interface for executing one Cycles simulation and reading its files.
 
-    Provides methods to run simulations, read outputs, and inspect soil/weather/operation
-    configurations. Automatically loads the control file upon initialization.
+    Provides methods to run simulations, read outputs, and inspect soil/weather/operation configurations. Automatically
+    loads the control file upon initialization.
 
     Attributes:
         path: Path to the simulation directory (containing input/ and output/ subdirs).

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_runner.py

@@ -29,9 +29,8 @@ class SimulationContext:
 class CyclesRunner:
     """Run one or many Cycles simulations with templated inputs.
 
-    Manages batch execution of Cycles simulations by generating control files,
-    operation files, and nudge files from templates and parameter dictionaries.
-    Consolidates results into a summary CSV file.
+    Manages batch execution of Cycles simulations by generating control files, operation files, and nudge files from
+    templates and parameter dictionaries.  Consolidates results into a summary CSV file.
 
     Attributes:
         executable: Absolute path to the Cycles executable binary.
@@ -110,7 +109,6 @@ class CyclesRunner:
 
 
     def _resolve(self, simulation: dict[str, Any], control_dict: dict[str, Any], operation_dict: dict[str, Any] | None, calibration_dict: dict[str, Any] | None) -> SimulationContext:
-        """Call control_dict once per row and resolve all derived values."""
         control = resolve_dict_values(control_dict, simulation)
         return SimulationContext(
             name=control['simulation_name'],

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_tools/__init__.py

@@ -9,13 +9,12 @@ from .soil_file import MAPPABLE_PARAMETERS
 from .soil_file import SoilLayer
 from .soil_file import generate_soil_file
 from .soil_file import read_soil_file
-from .soil_file import map_to_dataframe
-from .soil_file import from_dataframe
 from .weather_file import read_weather_file
 from .reinit_file import generate_reinit_file
 from .plot_tools import plot_yield
 from .plot_tools import plot_operations
 from .plot_tools import plot_map
+from .plot_tools import plot_satellite_map
 from ._base_file import resolve_dict_values
 
 __all__ = [
@@ -31,4 +30,5 @@ __all__ = [
     "plot_yield",
     "plot_operations",
     "plot_map",
+    "plot_satellite_map",
 ]

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_tools/_base_file.py

@@ -23,7 +23,7 @@ def write_file(fn: Path, config) -> None:
 
 
 def resolve_dict_values(user_dict: dict, simulation: dict[str, Any] | None) -> dict:
-    return {key: func(simulation) if callable(func) else func for key, func in user_dict.items()}
+    return {key.lower(): func(simulation) if callable(func) else func for key, func in user_dict.items()}
 
 
 def extract(dc_class, resolved: dict) -> dict:

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_tools/control_file.py

@@ -78,6 +78,35 @@ def _get_soil_layers(fn: Path) -> int:
 def generate_control_file(fn: str | Path, user_dict: dict, *, simulation_dict: dict[str, Any] | None=None) -> ControlConfig:
     """Generate and write a Cycles control file.
 
+    Provide either direct values or callables that accept a simulation row and return a value in `user_dict`. The
+    parameter names should be in lowercase and correspond to the fields in Cycles simulation control files. If a field
+    is not provided, it will be filled with a default value. If a field's value is a callable, it will be called with
+    the `simulation_dict` to resolve its value.
+
+    The following fields are required in `user_dict`:
+
+      - `simulation_start_year`
+      - `simulation_end_year`
+      - `rotation_size`
+      - `operation_file`
+      - `soil_file`
+      - `weather_file`
+
+    The default values for other fields are:
+
+      - `crop_file`: `GenericCrops.crop`
+      - `reinit_file`: `N/A`
+      - `soil_layers`: inferred from the soil file (if not provided)
+      - `co2_level`: `-999`
+      - `use_reinitialization`: `0`
+      - `adjusted_yields`: `0`
+      - `hydrology_option`: `1`
+      - `automatic_nitrogen`: `0`
+      - `automatic_phosphorus`: `0`
+      - `automatic_sulfur`: `0`
+
+    All output control fields default to `0`.
+
     Args:
         fn: Destination control file path.
         user_dict: Values or callables for control fields.

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_tools/nudge_file.py

@@ -45,6 +45,14 @@ def _build_nudge_config(user_dict: dict, simulation_dict: dict[str, Any] | None)
 def generate_nudge_file(fn: str | Path, user_dict: dict, *, simulation_dict: dict[str, Any] | None=None) -> None:
     """Write a Cycles nudge file from user-provided values.
 
+    Provide either direct values or callables that accept a simulation row and return a value in `user_dict`. The
+    parameter names should be in lowercase and correspond to the fields in Cycles nudge (calibration) files. If a field
+    is not provided, it will be filled with a default value. If a field's value is a callable, it will be called with
+    the `simulation_dict` to resolve its value.
+
+    The default values for all calibration multipliers are `1.0`, and the default values for `kd_no3` and `kd_nh4` are
+    `0.0` and `5.6`, respectively.
+
     Args:
         fn: Destination nudge file path.
         user_dict: Values or callables for nudge parameters.

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_tools/output_file.py

@@ -15,7 +15,7 @@ def _parse_units(lines: list[str], columns) -> dict[str, str]:
 
 
 def read_output(path: str | Path, output_type: str) -> tuple[pd.DataFrame, dict[str, str]]:
-    """Read one Cycles output table and associated unit strings.
+    """Read one Cycles output file and associated unit strings.
 
     Args:
         path: Directory containing output CSV files.

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_tools/plot_tools.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 import cartopy.crs as ccrs
 import cartopy.feature as feature
+import cartopy.io.img_tiles as cimgt
 import geopandas as gpd
+import math
 import matplotlib.lines as mlines
 import matplotlib.pyplot as plt
 import numpy as np
@@ -274,3 +276,48 @@ def plot_map(gdf: gpd.GeoDataFrame, column: str, *, projection: ccrs.Projection=
         ax.set_title(title) # type: ignore
 
     return fig, ax  # type: ignore
+
+
+def _zoom_from_extent(extent, *, desired_pixels: int=1024) -> int:
+    """Determine the appropriate zoom level for a given map extent.
+    Number of global tiles at each zoom level is 2 ^ zoom_level
+    """
+    PIXELS_PER_TILE = 256
+
+    dx = abs(extent[1] - extent[0])
+    dy = abs(extent[3] - extent[2])
+
+    return round(max(math.log(desired_pixels / PIXELS_PER_TILE * 180 / dy) / math.log(2), math.log(desired_pixels / PIXELS_PER_TILE * 360 / dx) / math.log(2)))
+
+
+def plot_satellite_map(fig: Figure, extent: tuple[float, float, float, float], *,
+    alpha: float=1.0, ax: tuple[float, float, float, float] | None=None, desired_pixels: int=1024, style: str | None=None) -> tuple[GeoAxes, ccrs.Projection]:
+    """Render a satellite basemap over a geographic extent.
+
+    Args:
+        fig: Matplotlib figure used to create the map axes.
+        extent: Geographic bounds as ``(west, east, south, north)`` in degrees.
+        alpha: Basemap transparency where ``1.0`` is fully opaque.
+        ax: Optional axes rectangle passed to ``Figure.add_axes``.  If omitted, a full-figure subplot is created.
+        desired_pixels: Target figure resolution in pixels used to estimate tile zoom.
+        style: Optional Cartopy GoogleTiles style string. If omitted, ArcGIS World Imagery tiles are used.
+
+    Returns:
+        Tuple containing:
+            - GeoAxes with the satellite basemap.
+            - Projection associated with the tile source.
+    """
+    GOOGLE_URL = 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}.jpg'
+
+    google_satellite = cimgt.GoogleTiles(url=GOOGLE_URL) if style is None else cimgt.GoogleTiles(style=style)
+
+    if ax is None:
+        ax = fig.add_subplot(1, 1, 1, projection=google_satellite.crs)  # type: ignore
+    else:
+        ax = fig.add_axes(ax, projection=google_satellite.crs)  # type: ignore
+
+    assert isinstance(ax, GeoAxes)
+    ax.set_extent(extent, crs=ccrs.PlateCarree())
+    ax.add_image(google_satellite, _zoom_from_extent(extent, desired_pixels=desired_pixels), alpha=alpha)
+
+    return ax, google_satellite.crs

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_tools/reinit_file.py

@@ -74,12 +74,12 @@ def _format_reinit_block(row: pd.Series, doy: int, n_layers: int) -> list[str]:
 
 
 def generate_reinit_file(out_path: str | Path, in_path: str | Path, doy: int) -> None:
-    """Write a reinit file for all years at a selected day-of-year.
+    """Write a re-initialization file from Cycles output for all years at a selected day-of-year.
 
     Args:
-        out_path: Destination reinit file path.
-        in_path: Simulation output directory or stem used by ``read_output``.
-        doy: Day-of-year extracted from reinit output.
+        out_path: Destination re-initialization file path.
+        in_path: Simulation output directory that contains Cycles output files.
+        doy: Day-of-year extracted from re-initialization.
     """
     out_path = Path(out_path)
     in_path  = Path(in_path)

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/cycles_tools/soil_file.py

@@ -215,50 +215,18 @@ def _parse_token(token: str, param: SoilParameter) -> str | int | float | None:
     return token
 
 
-def _row_to_layer(row: pd.Series) -> SoilLayer:
-    valid_fields = {f.name for f in fields(SoilLayer)}
-    kwargs = {col: (None if pd.isna(val) else val) for col, val in row.items() if col in valid_fields}
-    return SoilLayer(**kwargs)  # type: ignore
-
-
-def map_layers(profile: list[SoilLayer], target: list[SoilLayer]=DEFAULT_PROFILE, parameters: list[str]=MAPPABLE_PARAMETERS, soil_depth: float | None=None) -> list[SoilLayer]:
-    """Map measured soil properties onto a target profile.
-
-    The mapping is performed by overlap-weighted averaging for each requested
-    parameter, after trimming target layers to the effective profile depth.
-
-    Args:
-        profile: Soil profile layers in depth order.
-        target: Target layer structure to map onto.
-        parameters: Soil parameters to map from measured profile to target.
-        soil_depth: Optional maximum depth (m) to include in the mapped profile.
-
-    Returns:
-        A list of mapped soil layers aligned to the target profile.
-    """
+def _map_layers(profile: list[SoilLayer], target: list[SoilLayer]=DEFAULT_PROFILE, parameters: list[str]=MAPPABLE_PARAMETERS, soil_depth: float | None=None) -> list[SoilLayer]:
     trimmed = _trim(target, profile[-1].bottom, soil_depth)
     return [_map_layer(layer, profile, parameters) for layer in trimmed]
 
 
-def map_to_dataframe(layers: list[SoilLayer]) -> pd.DataFrame:
-    """Convert soil layers to a tabular representation.
-
-    Args:
-        layers: Soil layers to convert.
-
-    Returns:
-        A DataFrame with one row per layer, including computed ``thickness``.
-    """
-    return pd.DataFrame([{**asdict(layer), 'thickness': layer.thickness} for layer in layers])
-
-
 def generate_soil_file(fn: str | Path, profile: list[SoilLayer], *,
     target: list[SoilLayer]=DEFAULT_PROFILE, parameters: list[str]=MAPPABLE_PARAMETERS, soil_depth: float | None=None,
     desc: str='', slope: float | None=None, curve_number: float | None=None, hsg: str='') -> list[SoilLayer]:
-    """Map layers and write a Cycles-formatted soil file.
+    """Generate a Cycles-formatted soil file from a list of soil layers.
 
-    The input profile is first mapped to the target layering scheme, then
-    rendered to Cycles soil-file format and written to ``fn``.
+    The input profile is first mapped to the target layering scheme, then rendered to Cycles soil-file format and
+    written to ``fn``.
 
     Args:
         fn: Output soil file path.
@@ -279,7 +247,7 @@ def generate_soil_file(fn: str | Path, profile: list[SoilLayer], *,
     """
     if curve_number is not None and hsg:
         raise ValueError("Only one of curve_number and hsg can be provided.")
-    layers = map_layers(profile, target, parameters, soil_depth)
+    layers = _map_layers(profile, target, parameters, soil_depth)
     Path(fn).write_text('\n'.join(_render_soil_file(layers, desc, slope, curve_number, hsg)) + '\n')
     return layers
 
@@ -301,15 +269,3 @@ def read_soil_file(fn: str | Path) -> tuple[list[SoilLayer], dict]:
     meta, data_lines = _parse_header(lines)
     layers = _parse_layers(data_lines)
     return layers, meta
-
-
-def from_dataframe(df: pd.DataFrame) -> list[SoilLayer]:
-    """Convert a DataFrame into ``SoilLayer`` objects.
-
-    Args:
-        df: DataFrame containing columns matching ``SoilLayer`` fields.
-
-    Returns:
-        A list of ``SoilLayer`` instances created row-by-row.
-    """
-    return [_row_to_layer(row) for _, row in df.iterrows()]

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/gadm/__init__.py

@@ -7,7 +7,7 @@ from .gadm import county_fips
 from .gadm import county_gid
 from .gadm import county_name
 
-_all__ = [
+__all__ = [
     "read_gadm",
     "state_abbreviation",
     "state_fips",

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/rotation_builder.py

@@ -93,10 +93,9 @@ class RotationResult(NamedTuple):
 class CyclesRotationBuilder:
     """Run Cycles iteratively and append economically optimal operations.
 
-    Executes Cycles simulations for candidate crop-operation combinations,
-    selects the highest-return option at each break-point, and iteratively
-    builds a multi-year rotation. Integrates economic scoring with agronomic
-    constraints (e.g., minimum planting interval, crop group penalties).
+    Executes Cycles simulations for candidate crop-operation combinations, selects the highest-return option at each
+    break-point, and iteratively builds a multi-year rotation. Integrates economic scoring with agronomic constraints
+    (e.g., minimum planting interval, crop group penalties).
 
     Attributes:
         simulation: Base simulation name for generated input/output directories.

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/soilgrids/soilgrids.py

@@ -90,10 +90,8 @@ class SoilGrids:
         """Reproject loaded maps to a reference raster grid.
 
         Args:
-            reference_xds: Reference raster whose CRS, transform, and resolution
-                are used for reprojection.
-            reference_name: Column name used for the reference raster values in
-                the generated matched table.
+            reference_xds: Reference raster whose CRS, transform, and resolution are used for reprojection.
+            reference_name: Column name used for the reference raster values in the generated matched table.
             boundary: Boundary geometry used to clip all rasters after reprojection.
 
         Returns:
@@ -211,8 +209,8 @@ def download_soilgrids_data(path: str | Path, *,
     maps: list[str]=ALL_MAPS, boundary: Polygon | None=None, bbox: tuple[float, float, float, float] | None=None, crs: str='epsg:4326') -> None:
     """Download SoilGrids raster layers via WCS.
 
-    You can provide either a boundary polygon or an explicit bounding box.
-    Bounding boxes are expected in ``(west, south, east, north)`` order.
+    You can provide either a boundary polygon or an explicit bounding box.  Bounding boxes are expected in
+    ``(west, south, east, north)`` order.
 
     Args:
         path: Directory where downloaded GeoTIFF files are written.

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/cycles/ssurgo/ssurgo.py

@@ -90,8 +90,10 @@ class Ssurgo:
 
     def __init__(self, path: str | Path, state: str, *, lat_lon: LatLon | None=None, boundary: gpd.GeoDataFrame | None=None) -> None:
         """Initialize SSURGO lookup tables and optional spatial subset.
-        When a location (`lat_lon`) or boundary polygon is provided, the map-unit table is filtered to include only those map units that intersect the location or polygon;
-        the map-units are also grouped by name and symbol, and the major map unit is selected for profile extraction.
+
+        When a location (`lat_lon`) or boundary polygon is provided, the map-unit table is filtered to include only
+        those map units that intersect the location or polygon; the map-units are also grouped by name and symbol, and
+        the major map unit is selected for profile extraction.
 
         Args:
             path: Directory containing SSURGO geodatabase and lookup CSV files.

{cycles_utils-4.0.2 → cycles_utils-4.0.3}/setup.py

@@ -5,7 +5,7 @@ with open('README.md', 'r') as f:
 
 setup(
     name='Cycles-utils',
-    version='4.0.2',
+    version='4.0.3',
     author='Yuning Shi',
     author_email="shiyuning@gmail.com",
     packages=find_packages(),