numpy<3.0,>=1.24 PySide6<7.0,>=6.5 qtpy<3.0,>=2.3 python-dateutil<3.0,>=2.8 certifi>=2023.7.22 requests<3.0,>=2.28 metpy<2.0,>=1.5 ecape-parcel<2.0,>=1.2.2 [dev] pytest>=7.0 hypothesis>=6.0 [era5] herbie-data cfgrib xarray [render] requests<3.0,>=2.28 [wrf] xarray netCDF4 =========================================================================== SHARPpy Reimagined — INSTALLATION REFERENCE =========================================================================== Everything you need to INSTALL and run SHARPpy Reimagined is listed here. - How to USE the tools ..................... docs/USAGE.md - Narrative install walkthrough ........... README.md ("Installation") The Python import package is still named `sharpmod` (that is the module name and the pip distribution name); "SHARPpy Reimagined" is the project name. --------------------------------------------------------------------------- 1. SYSTEM REQUIREMENTS --------------------------------------------------------------------------- - Python >= 3.11 (64-bit; use 3.11-3.13 for Windows source GUI runs) - pip >= 23 (needed for editable installs + modern resolver) - OS : Windows, Linux, or macOS - Disk : ~1.5 GB for the full render + scientific stack - Network : required for `pip install`, UWyo fetch, and ERA5 retrieval - Display : required ONLY for the interactive desktop GUI (`sharpmod-gui`); CLI rendering runs headless (Qt "offscreen") and needs no display - Rust/Git: required only to compile `sharpmod_native` from a source checkout; standalone artifacts are built with the extension included --------------------------------------------------------------------------- 2. QUICK INSTALL (copy/paste) --------------------------------------------------------------------------- # 1) start from a repository checkout git clone https://github.com/FahrenheitResearch/SHARPpy-Reimagined-vRust.git cd SHARPpy-Reimagined-vRust # 2) create and activate an isolated environment python -m venv .venv # Windows PowerShell: .venv\Scripts\Activate.ps1 # macOS/Linux: source .venv/bin/activate python -m pip install --upgrade pip setuptools wheel # 3) core library + CLI tools + render transitive deps python -m pip install ".[render]" # 4) rendering engine (separate step -- see section 4 for why) python -m pip install --no-deps "SHARPpy==1.4.0a5" # 5) verify the packages needed by the GUI/renderer python -c "import sharpmod, sharppy, sutils, PySide6, qtpy; print('imports OK')" # 6) optional extras; use -e only when developing this checkout python -m pip install ".[era5]" # ERA5 point-sounding extraction python -m pip install ".[wrf]" # WRF-ARW (wrfout NetCDF) extraction python -m pip install -e ".[dev]" # run/edit the test suite # 7) optional for source installs: build the vRust analysis extension # (install a current stable Rust toolchain first; see section 5) git clone https://github.com/FahrenheitResearch/sharppyrs native/sharppyrs git -C native/sharppyrs checkout 958bcd685b1e28b8fce0ab5c7b8daea3cdd993aa git -C native/sharppyrs apply ../patches/sharppyrs-ecape-el.patch cargo build --manifest-path native/sharpmod-native/Cargo.toml --release --locked python packaging/install_native_extension.py --------------------------------------------------------------------------- 3. CORE RUNTIME LIBRARIES (installed by `pip install .` or `pip install -e .`) --------------------------------------------------------------------------- Package Version pin Purpose ---------------- --------------- ------------------------------------- numpy >=1.24,<3.0 arrays / numerical math PySide6 >=6.5,<7.0 Qt6 GUI toolkit (used for rendering) qtpy >=2.3,<3.0 Qt binding abstraction layer python-dateutil >=2.8,<3.0 flexible date/time parsing certifi >=2023.7.22 CA bundle for verified HTTPS fetches requests >=2.28,<3.0 HTTP (UWyo + SHARPpy datasources) metpy >=1.5,<2.0 meteorological calcs (ECAPE reference) ecape-parcel >=1.2.2,<2.0 analytic ECAPE fallback/reference Notable second-level libraries pulled in automatically (mainly by MetPy and PySide6), listed for offline mirrors / air-gapped installs: shiboken6, PySide6-Essentials, PySide6-Addons (Qt6 runtime) pandas, scipy, matplotlib, xarray, pint, pooch, pyproj, contourpy, kiwisolver, fonttools, cycler, pillow, pyparsing, packaging, platformdirs, flexcache, flexparser, traitlets, six, tzdata, urllib3, idna, charset-normalizer, typing-extensions (plus their own transitive dependencies) --------------------------------------------------------------------------- 4. RENDERING ENGINE — upstream SHARPpy (installed with --no-deps) --------------------------------------------------------------------------- Package : SHARPpy==1.4.0a5 Provides: sharppy, sutils, datasources, runsharp Install : pip install --no-deps "SHARPpy==1.4.0a5" WHY A SEPARATE --no-deps STEP: SHARPpy 1.4.0a5's wheel metadata pins `numpy==1.15.*`, which conflicts with the modern NumPy required above (a normal `pip install SHARPpy` would fail to resolve, or try to downgrade NumPy and break everything). Its real runtime needs — python-dateutil, requests, numpy — are ALREADY provided by the core install, so --no-deps is safe. NEEDED ONLY FOR RENDERING (`sharpmod-render` or any `--render` flag). Fetching/extracting soundings does NOT require it. --------------------------------------------------------------------------- 5. VRUST NATIVE ANALYSIS (source checkouts) --------------------------------------------------------------------------- The platform-specific `sharpmod_native` stable-ABI extension is included by the standalone packaging targets. A normal Python source install does not compile it automatically: follow quick-install step 7 when native analysis is wanted. The extension makes one GIL-free call into the pinned `sharppyrs` analysis layer and its `sharprs` core, with analytic ECAPE/NCAPE from `ecape-rs`. Detailed fire-PBL fields, precipitation-source/layer-energy analysis, SARS analog databases, and station PWV climatology remain explicit Python steps. If the extension is missing or cannot analyze a profile, the complete Python `ConvectiveProfile` is used, so source installs remain functional. Verify the installed extension and its pinned provenance: python -c "from sharpmod import sharpmod_native; print(sharpmod_native.backend_info())" Set `SHARPMOD_DISABLE_NATIVE_ANALYSIS=1` to force and test the Python fallback. --------------------------------------------------------------------------- 6. OPTIONAL EXTRAS --------------------------------------------------------------------------- [era5] ERA5 reanalysis and public forecast-model point extraction cdsapi, herbie-data, cfgrib, ecCodes, xarray, numcodecs, pyproj [wrf] WRF-ARW (wrfout NetCDF) point-sounding extraction xarray, netCDF4 [dev] test tooling pytest>=7.0, hypothesis>=6.0 --------------------------------------------------------------------------- 7. WHAT YOU NEED FOR EACH TASK --------------------------------------------------------------------------- Task Core +SHARPpy +extra ------------------------------------- ----- --------- ---------- Run the interactive GUI (sharpmod-gui) yes YES - List / search / fetch UWyo soundings yes no - Render a sounding to PNG yes YES - Extract an ERA5 point sounding yes no [era5] Extract a WRF-ARW point sounding yes no [wrf] Run the test suite yes YES [dev] The native extension is an accelerator, not a prerequisite for correctness. Standalone v0.3.2 build targets include it; source installs use the explicit Python fallback unless section 5 is completed. --------------------------------------------------------------------------- 8. CONSOLE COMMANDS INSTALLED --------------------------------------------------------------------------- sharpmod-gui interactive desktop app (station map / list / open file) sharpmod-render render a sounding file to PNG uwyo-sounding list / search / fetch University of Wyoming soundings era5-extract ERA5 point sounding -> .npz wrf-extract WRF-ARW point sounding -> .npz (sharpmod-gui is a windowed/no-console entry point; it needs a display and the SHARPpy render stack from section 4.) --------------------------------------------------------------------------- 9. VERIFY THE INSTALL --------------------------------------------------------------------------- # imports resolve python -c "import sharpmod, sharppy, sutils; print('imports OK')" # render a bundled example (needs the SHARPpy step) sharpmod-render examples/soundings/hrrr_point_36.68N_95.66W_f018.npz out.png # full test suite (needs [dev] + the SHARPpy step) pytest # native backend provenance (only after source-build step 7) python -c "from sharpmod import sharpmod_native; print(sharpmod_native.backend_info())" --------------------------------------------------------------------------- 10. TROUBLESHOOTING --------------------------------------------------------------------------- - "No module named sharppy/sutils" or a Qt enum error when rendering: pip install --no-deps "SHARPpy==1.4.0a5" - ResolutionImpossible mentioning numpy==1.15: you tried to install SHARPpy WITHOUT --no-deps; use the --no-deps form. - ImportError for herbie/cfgrib or netCDF4: install the matching extra: pip install -e ".[era5]" / ".[wrf]" - ERA5 reports missing CDS API credentials: create a free CDS account, accept the ERA5 pressure-level licence, then copy the profile from https://cds.climate.copernicus.eu/how-to-api into %USERPROFILE%\.cdsapirc (Windows) or $HOME/.cdsapirc. - A blank window / QpaPlatform error on a headless server: ensure QT_QPA_PLATFORM=offscreen (the renderer sets this by default). - `ImportError: cannot import name sharpmod_native` in a source checkout: build/install the extension as shown in quick-install step 7, or leave it absent and use the automatic full Python analysis fallback.