vtir-wizard 1.4.1__py3-none-any.whl

vtir_wizard/__init__.py

@@ -0,0 +1,34 @@
+"""vtir_wizard -- variable-temperature IR orchestrator for a Thermo Nicolet iS5
++ Specac heated Golden Gate ATR + Specac USB temperature controller.
+
+The package exposes three entry points:
+
+    vtir_wizard.orchestrator   the run wizard (``vtir-wizard`` console script)
+    vtir_wizard.temp_plot      live temperature/setpoint overlay window
+    vtir_wizard.ir_plot        live stacked-IR-spectrum window
+
+Only light-weight, dependency-free shared constants live in this top-level
+module so the plot subprocesses (which import ``SCHEDULE_KINDS``) don't drag in
+the orchestrator's pywin32 dependency.
+"""
+from __future__ import annotations
+
+__version__ = "1.4.1"
+
+# Single source of truth for per-direction metadata used across the wizard
+# summary (glyph), the per-step log line (arrow), and the live plots' overlay
+# shading (color, label).  Adding a new schedule kind means adding one row here
+# -- not editing four sites.  Background ("bg") is also listed even though it
+# isn't a step direction, because the live plots shade BG scans too.
+SCHEDULE_KINDS = {
+    "up":     {"glyph": "^", "arrow": "Heating up to",
+               "color": (1.0, 0.2, 0.2, 0.22), "label": "Sample (up)"},
+    "down":   {"glyph": "v", "arrow": "Cooling down to",
+               "color": (1.0, 0.6, 0.0, 0.25), "label": "Sample (down)"},
+    "return": {"glyph": "*", "arrow": "Cooling back to starting temperature",
+               "color": (0.2, 0.7, 0.2, 0.28), "label": "Sample (return)"},
+    "bg":     {"glyph": "B", "arrow": "(background, not a step)",
+               "color": (0.2, 0.2, 1.0, 0.18), "label": "Background"},
+}
+
+__all__ = ["__version__", "SCHEDULE_KINDS"]

vtir_wizard/config.py

@@ -0,0 +1,115 @@
+"""Config-file discovery and loading for the pip-installed wizard.
+
+When the project lived as loose scripts the config sat next to ``vt_ir.py``.
+Installed via pip the package lives in a read-only ``site-packages`` directory,
+so the editable ``vt_ir_config.ini`` must live somewhere the user owns.
+
+Resolution order (``resolve_config_path``):
+
+    1. an explicit ``--config PATH``                (always wins)
+    2. ``./vt_ir_config.ini`` in the current folder (per-experiment configs)
+    3. ``%APPDATA%/vtir-wizard/vt_ir_config.ini``   (the per-user copy)
+
+``vtir-wizard --init-config`` writes the packaged template to the per-user
+location so a fresh install has something to edit.
+"""
+from __future__ import annotations
+
+import configparser
+import os
+from pathlib import Path
+from typing import Optional
+
+APP_DIR_NAME = "vtir-wizard"
+CONFIG_NAME = "vt_ir_config.ini"
+
+
+# ---------------------------------------------------------------------------
+# Locations
+# ---------------------------------------------------------------------------
+def user_config_dir() -> Path:
+    """Per-user config directory.  ``%APPDATA%/vtir-wizard`` on Windows (the
+    documented target); falls back to ``~/.config/vtir-wizard`` elsewhere so the
+    package still imports/tests on non-Windows CI."""
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        return Path(appdata) / APP_DIR_NAME
+    return Path.home() / ".config" / APP_DIR_NAME
+
+
+def user_config_path() -> Path:
+    return user_config_dir() / CONFIG_NAME
+
+
+def packaged_template_text() -> str:
+    """The bundled template ``vt_ir_config.ini`` shipped under the package's
+    ``data`` directory.  Read through importlib.resources so it works from a
+    wheel, an editable install, or a source checkout."""
+    from importlib import resources
+
+    return (resources.files("vtir_wizard.data")
+            .joinpath(CONFIG_NAME)
+            .read_text(encoding="utf-8"))
+
+
+# ---------------------------------------------------------------------------
+# Resolution + loading
+# ---------------------------------------------------------------------------
+def resolve_config_path(explicit: Optional[str]) -> Optional[Path]:
+    """Return the config file to use, or ``None`` if nothing was found.
+
+    An explicit path that does not exist is a hard error (the user clearly meant
+    that file); the implicit search just falls through to the next candidate."""
+    if explicit:
+        p = Path(explicit).expanduser()
+        if not p.exists():
+            raise SystemExit(f"--config path does not exist: {p}")
+        return p
+    cwd = Path.cwd() / CONFIG_NAME
+    if cwd.exists():
+        return cwd
+    user = user_config_path()
+    if user.exists():
+        return user
+    return None
+
+
+def load_config(path: Path) -> configparser.ConfigParser:
+    cfg = configparser.ConfigParser(inline_comment_prefixes=("#", ";"))
+    cfg.read(path, encoding="utf-8")
+    return cfg
+
+
+def load_config_optional(path: Optional[Path]) -> configparser.ConfigParser:
+    """Tolerant load used by the plot helpers: returns an empty parser if the
+    path is missing, so a standalone plot window still starts."""
+    cfg = configparser.ConfigParser(inline_comment_prefixes=("#", ";"))
+    if path and Path(path).exists():
+        cfg.read(path, encoding="utf-8")
+    return cfg
+
+
+def init_user_config(force: bool = False) -> tuple[Path, bool]:
+    """Write the packaged template to the per-user config location.
+
+    Returns ``(path, written)`` -- ``written`` is False if the file already
+    existed and ``force`` was not given (so we never clobber a tuned config by
+    accident)."""
+    dest = user_config_path()
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if dest.exists() and not force:
+        return dest, False
+    dest.write_text(packaged_template_text(), encoding="utf-8")
+    return dest, True
+
+
+def missing_config_message() -> str:
+    """Actionable message when no config is found anywhere."""
+    return (
+        "No vt_ir_config.ini found.\n"
+        f"Looked for: ./{CONFIG_NAME} (current folder) and {user_config_path()}.\n"
+        "Create the per-user copy with:\n"
+        "    vtir-wizard --init-config\n"
+        "then edit it (the path is printed) and re-run.  Or pass an explicit\n"
+        "file with  --config <path>."
+    )

vtir_wizard/data/__init__.py

@@ -0,0 +1,2 @@
+# Marks vtir_wizard.data as a subpackage so the bundled vt_ir_config.ini template
+# is reliably importable via importlib.resources.files("vtir_wizard.data").

vtir_wizard/data/vt_ir_config.ini

@@ -0,0 +1,231 @@
+# =============================================================================
+#  vt_ir_config.ini  --  machine-specific paths and defaults for the VT-IR wizard
+# -----------------------------------------------------------------------------
+#  Edit the values below to match the lab PC.  Most lines have a comment that
+#  explains what changes if you tweak the value.  All path values are plain
+#  Windows paths (backslashes are fine -- no escaping needed in INI files).
+# =============================================================================
+
+[paths]
+# ---------------------------------------------------------------------------
+# Specac USB controller CLI.  Installed by the Specac controller installer at
+# this default location.  Confirm with:  where specac.cmd.exe
+# ---------------------------------------------------------------------------
+specac_exe = C:\Program Files (x86)\Specac\Temperature Controller\1.0\bin\specac.cmd.exe
+
+# ---------------------------------------------------------------------------
+# Where all collected spectra are written.  One sub-folder is created per
+# experiment, named after the sample (sanitized).
+# ---------------------------------------------------------------------------
+output_root = C:\Users\<you>\Documents\VT-IR\spectra
+
+# ---------------------------------------------------------------------------
+# Where to look for background files in sample mode.  Usually the same as
+# output_root -- BG files live in <bg_root>/<sample>/BG_<sample>_<T>C.SPA.
+# Override only if you collect BG files in a separate location.
+# ---------------------------------------------------------------------------
+bg_root = C:\Users\<you>\Documents\VT-IR\spectra
+
+# ---------------------------------------------------------------------------
+# Where the wizard drops its timestamped session log files.
+# ---------------------------------------------------------------------------
+log_dir = C:\Users\<you>\Documents\VT-IR\logs
+
+# ---------------------------------------------------------------------------
+# Where the Specac controller GUI writes its temperature .log files.
+# Used by the temperature overlay plot to find the active log.
+# ---------------------------------------------------------------------------
+specac_log_dir = C:\Users\<you>\Documents\Specac Temperature Controller\Logs
+
+# ---------------------------------------------------------------------------
+# Where the live overlay plot saves its SVG snapshots.  Parallel to the
+# spectra and log folders.  One sub-folder per sample is created here, and
+# snapshots are named  <sample>_<BG|SAMPLE>_<timestamp>.svg  so background and
+# sample plots stay distinguishable.  If left blank, defaults to a "plots"
+# folder next to output_root.
+# ---------------------------------------------------------------------------
+plot_dir = C:\Users\<you>\Documents\VT-IR\plots
+
+
+[defaults]
+# ---------------------------------------------------------------------------
+# Default OMNIC experiment file (.exp).  Loaded once at the start of each run
+# with the KeepBkg flag so subsequent BackgroundFileName pokes survive.
+# ---------------------------------------------------------------------------
+omnic_exp_file = C:\my documents\omnic\Param\VT_128_2.exp
+
+# Default temperature program -- accepts the (Tmin,Tmax,Tstep) range syntax or
+# a whitespace-separated list "50 75 100 150".
+temps_default = (50,200,20)
+
+# Allowed temperature window in C.  Hard guard against typos and against
+# exceeding the ATR cell rating.
+tmin = 20
+tmax = 250
+
+# Extra dwell at each set point after the Specac CLI returns "temperature
+# reached".  Useful for letting the sample (not just the cell body) reach
+# thermal equilibrium, and for damping any residual gradient near tolerance.
+# Default 120 s (2 min); tune down to ~30 s for fast empty-ATR test runs.
+equilibration_s = 120
+
+
+[omnic]
+# ---------------------------------------------------------------------------
+# How long to wait for a single CollectBackground / CollectSample to finish.
+# pywin32's DDE Exec call has a hard 60-second internal timeout, which is far
+# shorter than a real 128-scan @ 2 cm-1 collection -- so the wizard issues
+# collect commands with the 'Polling' keyword and waits in Python by polling
+# OMNIC's MenuStatus.  The two knobs below govern that polling loop.
+# ---------------------------------------------------------------------------
+# How often to query MenuStatus while waiting.
+poll_interval_s = 2
+
+# Hard cap on a single collection.  1800 s = 30 minutes; bump up only if your
+# experiment file legitimately runs longer than that per spectrum.
+collect_timeout_s = 1800
+
+# If OMNIC refuses to START a collection (the Polling Exec blocks ~60 s and
+# raises a DDE error -- usually the iS5 bench has gone offline / OMNIC is
+# wedged), the orchestrator reconnects the DDE channel and retries this many
+# times before giving up with an actionable message.  Set to 0 to disable
+# retrying.  Note: a hard bench wedge usually needs OMNIC restarted; retrying
+# only recovers transient DDE-channel glitches.
+collect_retries = 2
+
+# Seconds to wait between those retries.
+retry_delay_s = 5
+
+
+[live_plot]
+# ---------------------------------------------------------------------------
+# Auto-launch the temperature/setpoint overlay window when a run starts.  It
+# opens in its own console window AFTER the "Ready?" confirmation, locked onto
+# the current sample's session folder.  Close the window to dismiss it; the
+# orchestrator continues regardless.
+# ---------------------------------------------------------------------------
+# Set to false to disable auto-launch (or pass --no-live-plot on the CLI; note
+# --no-live-plot disables BOTH the temperature overlay and the IR stack window).
+enabled = true
+
+# Refresh interval in seconds.
+interval_s = 5
+
+# Estimated scan duration in seconds (used to draw the shaded scan band).
+# 210 s ~= 128 scans @ 2 cm-1.  Match this to your OMNIC .exp file.
+scan_duration_s = 210
+
+# How long after a run finishes the live plot waits before auto-saving its
+# SVG snapshot.  The delay lets the passive cool-down tail show up in the
+# saved image.  600 s = 10 min.  The plot ALSO saves immediately if you close
+# its window manually.
+save_delay_s = 600
+
+
+[ir_plot]
+# ---------------------------------------------------------------------------
+# Auto-launch the live stacked-IR-spectrum window alongside the temperature
+# overlay.  It re-reads the session's .SPA files as they land and re-draws a
+# temperature-colored waterfall of every scan so far.  After each new scan it
+# overwrites a SINGLE SVG at  <plot_dir>/<sample>/<sample>_IR_stack.svg  (only
+# the final stacked spectrum persists), in the same plot_dir as the temperature
+# snapshots.
+# ---------------------------------------------------------------------------
+# Set to false to disable just this window (or pass --no-ir-plot on the CLI).
+enabled = true
+
+# Layout:  stack   = fixed-offset waterfall (default)
+#          overlay = all spectra on a shared baseline
+mode = stack
+
+# Display unit:  A = absorbance,  T = %transmittance.
+unit = A
+
+# Refresh interval in seconds.
+interval_s = 5
+
+# Major x-tick spacing in cm-1 (0 = let matplotlib choose).
+tick_step = 500
+
+# Fixed vertical offset between stacked spectra.  Leave blank for an automatic
+# offset scaled to the data; set a number to pin it (stack mode only).
+offset =
+
+# Matplotlib colormap used to color spectra by temperature.
+cmap = gnuplot2
+
+# Figure sizing.  The saved SVG's HEIGHT grows with the number of spectra so a
+# tall stack keeps its peaks legible instead of squashing them into a fixed
+# canvas.  Raise height_per_spectrum to give each spectrum more vertical room.
+#   fig_width            - figure width in inches
+#   height_per_spectrum  - inches of height added per stacked scan (stack mode)
+#   max_height           - cap on the saved figure height in inches
+fig_width = 10
+height_per_spectrum = 0.5
+max_height = 30
+
+
+[export]
+# ---------------------------------------------------------------------------
+# Every collected spectrum is always saved as OMNIC's native .SPA (needed if
+# you ever want to re-process in OMNIC).  In addition, each spectrum is saved
+# in the formats listed below -- OMNIC picks the format from the extension.
+#
+# Comma-separated list of extensions (without the dot).  Common choices:
+#   csv  -> comma/tab-separated X,Y text  (best for most plotting tools)
+#   jdx  -> JCAMP-DX spectroscopy text    (.dx is the same format; use 'jdx'
+#                                          if your reader is picky -- it's the
+#                                          extension OMNIC documents)
+#   tif  -> image
+# Leave blank to save ONLY .SPA.  Examples:  csv   |   csv,jdx   |   (blank)
+# ---------------------------------------------------------------------------
+additional_formats = csv
+
+
+[backgrounds]
+# ---------------------------------------------------------------------------
+# How sample collections pick the background to ratio against.  Backgrounds
+# do NOT have to match the sample temperature exactly -- the heated cell sits
+# in a controlled glovebox -- so mismatches and old backgrounds are WARNED
+# about (and logged for the audit trail) but never block a run.
+# ---------------------------------------------------------------------------
+# Default temperature-matching mode (the wizard asks each run, pre-filled with
+# this):
+#   exact   - use the BG collected at each sample temperature (fails only if a
+#             temperature has no BG at all -- then it suggests closest/fixed)
+#   closest - use the nearest-temperature BG available for each step
+#   fixed   - use ONE background (chosen at the prompt) for every step
+match_mode = exact
+
+# Warn (but never block) when a chosen background file is older than this many
+# days.  The warning is written to the run log so there is a record of exactly
+# which (possibly old) background each measurement used.
+max_age_warn_days = 1
+
+# Minutes written to OMNIC's Collect/MaxBackgroundAge (with BackgroundHandling =
+# AfterTime) so OMNIC silently reuses the background the wizard binds instead of
+# stopping to ask "the background is old -- collect a new one?".  That prompt is
+# a modal dialog that blocks the DDE call and hangs the run, so this is set huge
+# by default (~1.9 years).  The wizard applies this over DDE every run, but the
+# primary fix is to ALSO select "Background after N minutes" with this value in
+# the OMNIC experiment (.exp) and SAVE it.  Lower only if you actually want OMNIC
+# to force a fresh background after some age.
+max_bg_age_min = 999999
+
+
+[heater]
+# ---------------------------------------------------------------------------
+# Specac controller settings.  Applied at the start of every run.
+# ---------------------------------------------------------------------------
+# +/- tolerance window (in deg C) used by the "sp <T> w" wait.
+tolerance_c = 1
+
+# Ramp rate in C/min.  Specac default 50 has been calibrated; only change with
+# a re-calibration (the old make_temperature_program.py picked timings based on
+# this value).
+ramp_c_per_min = 50
+
+# Timeout for any single "go to setpoint and wait" call, in seconds.  3600 = 1h.
+# Generous -- a real ramp 30 -> 250 C at 50 C/min plus settling is well under
+# 10 minutes, so this only fires if the controller hangs.
+ramp_timeout_s = 3600