io.github.fieldcure/zstudio

Adds a folder to a loaded study, under the given parent folder or at the top level. Returns the new folder's id-handle (fd_…). Auto-saves the study.

Runs one analysis across many datasets in parallel — the fan-out companion to the single- dataset analysis tools. Use it to apply the same step to a whole study (or a chosen subset) in one call: a Kramers-Kronig quality gate over every dataset, a DRT pass, or an equivalent-circuit guess / fit. kind selects the analysis: - 'kk' — Kramers-Kronig validation (data-quality gate). - 'drt_tikhonov' — Tikhonov DRT (γ(τ) distribution). - 'guess_ecm' — ECM initial-value estimation only (no optimization). - 'fit_ecm' — ECM non-linear fit (auto-seeds per dataset). For 'guess_ecm' / 'fit_ecm': OMIT cdc to use EACH dataset's OWN stored circuit (the model already on it — the right choice for a mixed study whose datasets have different circuits); PASS a cdc to apply the same circuit to every dataset (a homogeneous study). A dataset with neither is reported as an error and skipped. fit_ecm seeds from the structural estimator by default (seed_from='stored' uses the dataset's stored model). cdc / seed_from are ignored for kk / drt_tikhonov. Operations on different datasets run concurrently (bounded by max_parallel) and are isolated: each result is written only to its own dataset, the study is saved once at the end, and one dataset's failure never stops the others. Returns a token-light per-dataset summary (datasetId, name, ok, pseudoChiSquared / rSquared / circuit, or error) — for a chart or full detail, call the single-dataset tool on a specific dataset afterwards. Requires a study_id. Omit dataset_ids to run on every dataset in the study.

Returns the complete ZStudio equivalent-circuit notation reference as Markdown: operator precedence, naming, every circuit element (impedance + parameters), the lad() transmission-line options, and the Wheatstone bridge. Call this once to learn the full CDC vocabulary before constructing or fitting a circuit; use parse_circuit to validate a specific circuit and get its exact fittable parameters.

Clears every mask on a dataset, restoring all measured points to included. Stored analyses are NOT recomputed automatically — rerun kk / drt_* / guess_ecm / fit_ecm to use the full spectrum again. The study auto-saves unless ZSTUDIO_AUTOSAVE=off. Requires a study_id and dataset_id.

Releases a DC series read with read_dc_file from the session (its dc_id stops working). Files already exported are not touched.

Removes a loaded study from the session, freeing its memory. Analysis results are auto-saved to the study's .zstudy after each tool call, so closing does not lose work (unless auto-save was disabled with ZSTUDIO_AUTOSAVE=off, in which case save_study first).

Imports a raw vendor EIS data file and writes a ZStudio .zstudy document. Supported formats are auto-detected: BioLogic (.mpr/.mpt), Gamry (.DTA), Scribner/ZView (.z), Ivium (.ids/.idf), EcoChemie (.dfr), Elchemea (.i2b), MinTech, and generic text (.csv/.tsv/.txt/.dat). USE WHEN: the user wants to convert/import a measurement file into a .zstudy, or start a study from raw data. When the user wants to ANALYZE the file in the same conversation, pass open_session=true — the created study is loaded into the session and the result also carries study_id, the tree, and dataset_id handles, so no separate open_study call is needed. Returns a token-light summary (per-dataset name, point count, frequency range, detected vendor format) — never the raw spectrum. If output_path is omitted, the .zstudy is written (atomically) to the working directory — the ZSTUDIO_WORKDIR environment variable, or a 'ZStudio' folder under the user's Documents — named after the study; the actual path is returned. Headerless data files (a bare numeric CSV/TSV with no header row) are supported; use headerless_format to say how the columns are laid out.

Runs Loewner-method DRT — the data-driven, regularization-free alternative to drt_tikhonov. It extracts discrete RC/RL poles directly from the spectrum (no λ to tune); each pole is one relaxation. Order selection (model_order_method / singular_value_threshold / model_order) controls how many poles are kept. The Loewner framework requires the IMPROPER part of the response removed — the series terms Rs (constant) and jωLs (unbounded) — which otherwise create spurious poles. The parallel stray Rp|Lp is PROPER (bounded: → Rp as f→∞), so it is NOT removed: it stays in the data and is captured as a native negative-γ (RL) pole. What is de-embedded is governed by stray_mode: • 'auto' (DEFAULT) — auto-detect the stray via a preliminary Loewner pass and de-embed the improper series terms (Rs + jωLs). A parallel Rp|Lp, when present, is detected and reported but LEFT in the data as a pole. On a clean strictly- proper spectrum nothing is detected, so it is safe to leave on. • 'manual' — use the exact Rs/Ls/Rp/Lp/Rx/Lx you pass via estimated_rs/ls/rp/lp/rx/lx: Rs+Ls are de-embedded; the parallel R|L pairs Rp|Lp and Rx|Lx are reported and drive the inductive-free deliverable. • 'none' — LEGACY / no de-embedding. Use only to reproduce the raw, un-de-embedded behavior; the pole count is then NOT a trustworthy time-constant count if any inductive tail or DC offset is present. In 'auto' and 'manual' the improper series impedance (Rs + jωLs) is removed from BOTH the measured and reconstructed spectra (never added back), so poles, χ², and residuals share one basis; a parallel Rp|Lp stray appears as an RL pole. estimate_inductance gives the same Rs/Ls/Rp/Lp diagnostic in detail, and export_inductive_free returns the spectrum with the inductive stray removed but Rs kept. Returns a token-light summary — poles (τ in s, f_peak in Hz, R in Ω; R<0 is an RL pole) and the resolved model order k, plus de-embedding provenance the mode…

Runs Tikhonov-regularized DRT — the continuous γ(τ) distribution. Resolves the impedance into relaxation processes along the time-constant (τ) axis; the peak count and positions guide equivalent-circuit choice (each peak ≈ one RC time constant). This is the regularized method — λ trades smoothness against fit. For the regularization-free, data-driven discrete-pole alternative use drt_loewner. The peak count is only a trustworthy time-constant count once series/stray impedance is removed. If the dataset summary shows an inductive tail (HasInductiveTail), enable de-embedding: include_series_inductance / include_series_capacitance add Ls/Cs terms, and inductance_handling selects the high-frequency inductive treatment as a single either/or choice — 'stray' de-embeds the full inductive stray (series Ls + parallel Rp|Lp, and Rx|Lx when present; subtract before the DRT analysis, add back — Ls is handled here, so include_series_inductance is ignored), 'gdrt' runs Generalized DRT (an RL distribution for in-band distributed inductance; Rs is pinned to the Löwner estimate because a free Rs is unidentifiable in the joint RC+RL fit — series cable inductance still needs include_series_inductance), and 'none' leaves it to the RC fit. For a precise Rs/Ls/Rp/Lp/Rx/Lx diagnostic without running DRT, use estimate_inductance. Returns a token-light summary — peaks (τ in s, f_peak in Hz, R in Ω), pseudo χ², λ — a fit-residual description (measured vs DRT reconstruction: maxAbs/meanPct, exceedBands, runs-test verdict), and a γ-vs-log-τ curve. It also carries curveShape — a geometric reading of the γ(τ) plot itself (the way the plot tool's `shape` reads a Bode/Nyquist plot). Narrate the distribution from it, not from the peak count alone: `segments` walks the curve high→low frequency labeling each region (baseline / rise / peak / shoulder / fall / valley); a peak/shoulder segment carries its apex f, γ height, fwhmDecades (broad vs sharp), areaOhm (≈ its R),…

DIAGNOSTIC / ALGORITHM-DEVELOPMENT tool (work in progress). Estimates the series/stray impedance — series Rs + jωLs plus up to two parallel R|L (Rp|Lp, Rx|Lx) — for the Loewner DRT de-embedding. Loewner requires the IMPROPER part removed (Rs constant + jωLs unbounded; Z→0 as f→∞); a parallel R|L is bounded (→ R as f→∞) and is KEPT as a native pole, not removed. So only Rs+Ls are de-embedded for the analysis basis; the R|L are reported and drive the inductive-free deliverable. Unlike the other analysis tools this is intentionally verbose and side-effect-free: it runs the preliminary Loewner pass and EXPOSES its internals — the top |λ|-sorted eigenvalues (each with its residue and γ=−Re(r/λ): γ>0 ⇒ capacitive R|C pole, γ<0 ⇒ inductive R|L stray pole), |λ1|/|λ2| and |λ3|/|λ4| gap ratios, Taylor coefficients c0…c3, the detected case (ls_pair / rplp_triplet / none), the Rp strategy (pole_id / c2_fallback), the SVD singular-value spectrum (model order), the estimated Rs/Ls/Rp/Lp/Rx/Lx, and — when it cannot estimate — WHY: rsSource (eigen / poles / imz_crossing / re_at_fmax), loewnerFailed, and a terminal verdict (ok / no_inductive_element / loewner_failed / rs_fallback), plus a step-by-step notes trace. These come straight from the production estimator (EISAnalyzer.EstimateSeriesAndStrayImpedance) — same numbers the DRT/Loewner path uses — so the algorithm can be reviewed and refined together. It does NOT modify the dataset. Returns a Nyquist overlay of the measured vs inductance-removed spectrum. (Intended to feed K-K eventually; not yet wired.) Also returns an 'overlap' block — the newer residue-sign classifier (EISAnalyzer.DiagnoseHfStrayOverlap, diagnostic-only, does not change the de-embedding): classification (None / FastRcResolved / FastRcOverlap / NonIdentifiable), the removable stray Rs/Ls/Rp/Lp (and the second R|L Rx/Lx) read from the eigenvalue Taylor coefficients (c0=Rs, c1=Ls/Lp, c2=−Lp²/Rp — so Rp/Lp are recovered even when t…

Evaluates an equivalent circuit at the CURRENT parameter values without estimating or fitting - the middle step of guess -> adjust -> fit, and the same thing the app does when a value is edited in the ECM panel: recompute pseudo chi-squared, R-squared and every parameter's standard error at the given state. Starts from the dataset's stored modeling state (the result of guess_ecm, a previous evaluate_ecm, or a fit) when it belongs to the same circuit; parameters="Rct=120,..." overrides only the named values, so consecutive calls compose exactly like consecutive edits in the app. The evaluated state is persisted back to the modeling store, and fit_ecm with seed_from='stored' then fits FROM this state. Use it to test "what if this parameter were X" hypotheses cheaply, to quantify how much a manual adjustment improves the start point before fitting, or to read uncertainty numbers at a hand-tuned state.

Writes a DC series (from read_dc_file) at full resolution for an external model: a CSV with every row (no decimation) plus <name>.meta.json describing each column (meaning, unit, origin, source column) and the source file (path, SHA-256, technique). Returns the paths, the row count (always the full series) and SHA-256 of the CSV. - CSV: header "name [unit]"; first columns "row" (source row number) and "time [s]" (instrument time axis, not rebased); invariant-culture, round-trip numbers (single-precision source values keep their stored value); empty cell = no value. - columns: comma/space-separated channel/marker names (default all). - include_interval_current: also writes <name>_interval_current.csv (one row per interval between consecutive rows: start/end row and time, current [mA], status), a derived value -- not a measured current. - output_path: default <working directory>/<source name>_dc.csv. Existing files are not replaced unless overwrite=true.

Exports the INDUCTIVE-FREE spectrum — the measured impedance with the inductive stray removed (series jωLs and the parallel R|L elements Rp|Lp and Rx|Lx) but the physical series resistance Rs KEPT. This is the HF-cleaned deliverable: raw − jωLs − Z_RpLp − Z_RxLx, where Z_R|L(s) = s·R·L / (R + s·L). Note this is NOT the Loewner DRT de-embedding, which additionally removes Rs (and keeps the R|L as native poles) — here Rs stays. Provenance: when a Loewner result is stored on the dataset, its already-materialized inductive-free spectrum is served as-is (source='stored_loewner') using that run's stray values — no recompute. Otherwise the stray (Ls, Rp, Lp) is estimated on demand via the same production estimator (source='on_demand_estimate') and the spectrum is computed from it; this is fast. Returns the inductive-free spectrum points (freqHz, zReOhm, zImOhm), the stray values used (rsOhm KEPT; lsHenry / rpOhm / lpHenry removed), the source, and a measured-vs- inductive-free Nyquist overlay. Requires a study_id and dataset_id. Runs on the selected data source. Side-effect-free.

Exports a loaded study to an .xlsx workbook — a re-analyzable data container with a stable English schema: README, Study, Datasets, Tree, the raw and Z-HIT-corrected point tables, per-dataset summaries, an analysis dashboard, and ECM results / parameters / options. Numeric cells stay numeric (SI base units, with units in the column headers); point data is long-form, one row per (dataset, point), joined on a workbook-local DatasetId. Exports every dataset in study tree order. Path resolution: an explicit .xlsx path if given, else the study's bound path with a .xlsx extension, else a new file in the working directory (ZSTUDIO_WORKDIR or ~/Documents/ZStudio). Read-only — it changes nothing in the study or on disk besides writing the workbook. USE WHEN: the user wants the study's data and results as a spreadsheet for external analysis or sharing. Requires a study_id from open_study / new_study / create_from_file.

Fits an equivalent-circuit model to a dataset's measured spectrum — the inverse of simulate_circuit (data + circuit → fitted parameters). Give the circuit as a CDC string (validate it and learn its parameter names first with parse_circuit); the fitter seeds initial values automatically, so initial/bounds/fixed are all optional. Runs a weighted non-linear least-squares fit on the dataset's selected data source (raw, or Z-HIT corrected if you called set_analysis_source). Returns a token-light summary — each parameter with its fitted value, units, and uncertainty (std error %, t-statistic, p-value, dependency), plus goodness-of-fit (pseudo χ², R², adjusted R², RMSE), iteration count, exit condition, and bound-hit flags — and a chart overlaying the measured data (markers) with the fitted model (dashed line). The result is stored on the dataset and the study auto-saves. Defaults: modulus weighting (1/|Z|², the EIS standard — far more robust on real data than equal weighting) and Levenberg-Marquardt. LM is a LOCAL optimizer: from a poor start it can stall or land in a local minimum. So READ THE RESULT and iterate: - exit_condition != "Converged", low R², or a huge residual → first retry from a better start (pass initial=…); then switch algorithm to a trust-region variant ('trust_region_dogleg' or 'trust_region_newton'). LM and the trust-region methods are the two workhorses — alternate between them; the variants behave differently per problem, so if one gives a poor result, try another or go back to LM with a different start. 'trust_region_exact' is the most thorough but is sensitive to parameter scaling — reach for it last, not first. - parameters_estimated=false → auto-seeding failed; supply initial values. - a parameter pinned at a bound (bound_hit), or two parameters with dependency≈1, → the circuit is over-specified; drop/fix an element or widen bounds. - a free parameter with UNDETERMINED statistics (null std error…

Returns the analysis results ALREADY STORED on a dataset — WITHOUT re-running anything. This is how you read back a prior fit_ecm / drt_loewner / kk / drt_tikhonov / zhit result (e.g. after reopening a .zstudy, or to inspect a dataset analyzed earlier in the session) instead of recomputing it. The analyses flags from get_dataset / open_study tell you which results are present first. Reports, for the dataset's currently selected data source, whichever results exist (the rest are null): - ecm: the fitted circuit, goodness-of-fit (pseudo χ², R², adjusted R², RMSE), and every fitted parameter with its value, units, and uncertainty — the same parameter detail fit_ecm returns (minus run-time-only metadata such as iteration count, which is not persisted). - loewner: the series/stray impedance (Rs/Ls + the parallel R|L pairs Rp/Lp and Rx/Lx; Rs+Ls de-embedded, the R|L kept as native poles), the model order, and the significant relaxation poles (τ, f_peak, R; R<0 = RL) — the same pole list drt_loewner returns. - kk / drtTikhonov / zhit: the goodness-of-fit headline plus the options that were used and the analysis date (kk also reports validity and the time-constant count). Every result carries the options it was produced with (read from the result's own stored state, exactly like the app's Results-panel "copy"). Read-only: no chart, no recomputation, and the study is not modified. For the chart, full residual description, or to change options, call the matching analysis tool (which recomputes). Requires a study_id and dataset_id.

Returns the actual measured points of a dataset, column-oriented and token-budgeted — the drill-down for when the token-light summary/shape (or a DRT curveShape) isn't enough but you don't want to render an image. Real measured points only (no interpolation), thinned to a budget and optionally restricted to a frequency window. - max_points (default 24, capped at 200): the curve is decimated to at most this many log-spaced points. Raise it for a closer look at a feature. - freq_min / freq_max: restrict to a frequency window — page through a spectrum by narrowing the window across calls. nTotalInWindow reports how many measured points the window actually holds, so you know whether more detail exists than was returned (decimated = true). - representation: 'nyquist' returns fHz + zReOhm + zImOhm (complete — derive |Z|, phase, admittance yourself); 'bode' returns fHz + zMagOhm + phaseDeg. - source: 'selected' (the dataset's active source), 'original', or 'zhit_corrected'. - include_excluded: default false drops masked points. Set true (with source='original') to see masked points plus per-point Index + Excluded columns, then feed Index to set_point_exclusions to curate exclusions. Use this only after the shape description; prefer plot for a visual on a chart-capable host. Requires a study_id and dataset_id.

Returns the token-light summary of one dataset: point count, frequency range, Nyquist geometry (Rs, Rp, R_total, |Z| and phase ranges), shape flags, and which analyses are already stored — never the raw spectrum. Read the stored results themselves (fitted ECM parameters, Loewner poles, K-K / DRT / Z-HIT) with get_analysis — no re-running required. Set include_shape to also attach the geometric shape description (§4) — the same −Z″ peaks / arc CPE-n / |Z| slope bands / LF-termination narration the plot tool returns — so you can reason about the curve's form without plotting it. (Structural counts like the number of RC processes still come from a DRT run, not the shape.) USE WHEN: you need a closer look at a specific dataset. Requires a study_id (open_study) and dataset_id (open_study/list_tree).

Returns descriptive, non-numeric properties of a dataset: provenance and acquisition metadata (source format, instrument, technique, DC/AC bias, timestamps), point counts, and which analyses are stored. For the numeric Nyquist geometry use get_dataset.

Returns original rows of a DC series (from read_dc_file) at full resolution: every point, in acquisition order, never decimated or interpolated. Large results are paged -- request the next page with offset = nextOffset until nextOffset is null, and all matching rows will have been returned. - Filters (optional, combined): time_min_s / time_max_s (instrument time axis, inclusive), half_cycle, step, loop. - columns: comma/space-separated channel/marker names from read_dc_file (default all). "row" (source row number) and "time [s]" are always the first two columns. - limit: rows per page (default 200 -- a page size, not a cap on the data; no fixed upper limit); offset: first matching row. nTotal is the number of matching rows. - include_interval_current: adds interval_current [mA] = charge increment / elapsed time, attributed to the END row of each interval (row i covers rows i-1..i; row 0 of the file has none), plus interval_current_exclusion (0 ok, 1 non-positive duration, 2 crosses a mode/direction/step/half-cycle/ cycle/loop switch, 3 missing data). It is a derived value, not a measured current. Rows are arrays aligned with columns; null means the row has no value (e.g. a voltage setpoint in a CC row). For a file to hand to a model, prefer export_dc_data.

Returns study-level metadata: name, description, author, timestamps, sample fields (id/name/note/type), measurement environment, and dataset count.

Estimates initial parameter values for an equivalent circuit from the dataset's spectrum WITHOUT fitting - the app's "estimate initial values" button as a tool, and the first step of the guess -> adjust -> fit workflow. The structural analysis derives the circuit's RC pairs from the topology and reads their values off the measured spectrum; the guessed model is then evaluated as-is (zero iterations) so the summary carries honest goodness-of-fit numbers for the START POINT, and the guess is stored on the dataset's modeling store (visible in the app). The estimator is deterministic and state-independent: it depends only on the data and the circuit, never on values the model carried before. That makes the workflow composable - to adjust the guess, call fit_ecm with ONLY the parameters you want to change in initial={...}; every untouched parameter is re-derived to exactly the value this tool returned. parameters_estimated=false means the estimator declined (it could not handle the topology) and the returned values are the factory defaults - then supply your own initial values to fit_ecm instead.

Imports a raw vendor EIS file into an already-loaded study, adding one dataset per measurement under the chosen folder (defaults to Inbox). Returns the new dataset id-handles and token-light summaries — never the raw spectrum. Auto-saves the study. Headerless data files (a bare numeric CSV/TSV with no header row) are supported; use headerless_format to say how the columns are laid out.

Runs a Kramers-Kronig (K-K) validation — the data-quality gate. K-K fits a K-K-compliant model and reports whether the spectrum is internally consistent (causal/linear/stable); large residuals flag drift, nonlinearity, or instrument artifacts. Runs on the dataset's currently selected data source (raw, or Z-HIT corrected if you called set_analysis_source). Returns a token-light summary plus an R/C-vs-τ chart — the resistance and capacitance of each fitted Voigt RC element vs its time constant (dual axis). For the measured-vs-recon residual *plot*, call plot(kind=residual, analysis=kk). The summary still carries the residual description so you can read fit quality without a plot: - pass, pseudoChiSquared, timeConstantCount. - residuals.maxAbsPct / meanAbsPct + maxAtHz: residual size and where. - residuals.exceedBands: frequency ranges where |residual| exceeds ~1%. - residuals.signRunZ / systematic: a runs test on the residual sign sequence. |z| > 2 ⇒ systematic (residuals cluster by sign — model misfit, drift, or non-stationarity), not random scatter. - residuals.verdict: 'ok' (small, random), 'noisy' (large but random), or 'systematic' (structured deviation). A 'systematic' verdict means the data — not just the noise — violates K-K; consider Z-HIT or excluding artifact points before trusting downstream DRT/ECM fits. The result is stored on the dataset and the study auto-saves. test_type is one of the two single-component tests: 'real' fits the real part and predicts the imaginary (real→imaginary); 'imaginary' does the reverse. The engine's combined 'complex' test is intentionally not offered — it is much slower. For a complex-style check, run kk twice (test_type='real' then 'imaginary') and compare the two residual descriptions: if both pass with small, random residuals the spectrum is K-K consistent; a component that fails one direction localizes the inconsistency. Other tuning (optional; defaults reproduce the app): impl…

Reports this MCP server's licensing state: 'Licensed' (a ZStudio license with the AI/MCP entitlement is active), 'Trial' (no key — the time-limited alpha trial is running), or 'Unlicensed' (trial expired or the key lacks the AI entitlement; tool calls are refused). Includes the trial days remaining when on trial and a human-readable message. Always callable, even when tool execution is otherwise blocked — use it to see why calls are refused and how to activate (set ZSTUDIO_LICENSE_KEY to a license that includes the AI (MCP) add-on).

Lists ZStudio's built-in equivalent-circuit model catalog (the app's Model Workshop): ~45 vetted models across the categories Simple, Diffusion, Porous, Battery, Corrosion, and Dielectric. Each entry carries the CDC circuit, typical parameter values (physically plausible magnitudes), and the recommended frequency window / points-per-decade for simulation. HOW TO PICK A MODEL for a measured spectrum: 1. Run drt_tikhonov (or drt_loewner) first — the number of resolved peaks/poles bounds how many time constants the data supports. 2. Use the sample context (battery cell, corroding metal, porous electrode, dielectric, ...) to choose the category, then shortlist 2-4 circuits whose structure matches the evidence (diffusion tail -> lad(...) line, depressed arc -> Q, blocking low-frequency rise -> series C, ...). 3. Screen the shortlist with guess_ecm (estimate-only): keep candidates whose data-derived guess already reproduces the spectrum shape. 4. Decide with fit_ecm: compare R²/χ² across candidates and reject over-parameterized ones via parameter dependencies, undetermined (null) statistics, and std errors. The typical values are catalog defaults for simulate_circuit, teaching, or eyeballing magnitudes — guess_ecm/fit_ecm derive initial values from the data instead. For the CDC grammar see circuit_reference; for one circuit's exact fittable parameters see parse_circuit. User-defined Workshop models are not exposed. Pure catalog — no dataset needed.

Lists everything loaded in this session: every study (study_id, name, dataset count, bound file path) and every DC time series read with read_dc_file (dc_id, source file, technique, row count). USE WHEN: you need to recover study_id / dc_id handles or check what is loaded.

Lists the .zstudy files saved on disk in the working directory — the ZSTUDIO_WORKDIR environment variable, or a 'ZStudio' folder under the user's Documents — so you can discover existing studies to open_study. Pass directory to list a different folder instead. Returns the resolved directory and, per file, its name, full path, size, last-modified time (newest first), and whether it is already open in this session. Reads the directory only — opens nothing. USE WHEN: the user refers to a saved study without giving a path, or you need to find what studies exist before opening one.

Returns the folder/dataset hierarchy of a loaded study, with id-handles for every node (fd_… folders, ds_… datasets) and dataset summaries. USE WHEN: you need the current structure or have lost track of the dataset_id handles. Requires a study_id from open_study.

Moves a folder or dataset into another folder (use the study id as the target for the top level). The root and the default Inbox folder cannot be moved, and a folder cannot move into its own subtree. Auto-saves the study.

Creates a new, empty study in the session (with a default Inbox folder) and returns its study_id. Use import_data to add measurements. The study auto-saves into the working directory on its first change; use save_study only to choose a different path.

Opens a .zstudy in the ZStudio desktop application (Windows) so the user can view and work with it in the full GUI — interactive Nyquist/Bode plots, the model workshop, etc. Launches via the .zstudy file association, so ZStudio must be installed on this machine. Give a study_id (from open_study/new_study/create_from_file) to open the current session study — it is saved first (atomically, to its bound path or the working directory) so the app opens exactly the current state, including analysis results. Or give an explicit path to open an existing .zstudy file. USE WHEN: the user wants to "open this in ZStudio", inspect a study visually, or hand off to the desktop app. Returns the path opened.

Loads a ZStudio .zstudy document into the server session and returns a study_id handle, the folder/dataset tree, and a token-light summary of every dataset (frequency range, Nyquist geometry, analysis flags) — never the raw spectrum. USE WHEN: the user wants to inspect, analyze, or continue working with an existing .zstudy file. Keep the returned study_id and dataset_id handles for follow-up calls (list_tree, get_dataset, save_study).

Validates a ZStudio equivalent-circuit string (CDC) and expands it into its canonical form, impedance formula, element list, and fittable parameters. Use it to check a circuit is valid and to see exactly which parameters fit_ecm will fit — before calling fit_ecm. CDC GRAMMAR (operator precedence, high → low): 1. transmission line: 'Z1 ... Z2' (W), 'Z1 .-. Z2' (T), 'Z1 .|. Z2' (O) — or the function form lad(Z1, Z2, OPT), OPT ∈ W O T K I S X B P. 2. parallel: '|' '||' '‖' (function: par(Z1, Z2, …)) 3. series: '+' '-' (function: ser(Z1, Z2, …)) PARALLEL BINDS TIGHTER THAN SERIES: "R1-R2|C1" == "R1-(R2|C1)". Brackets () [] {} are equivalent and override precedence. Short = 0, open = 'oo' or '∞'. Wheatstone bridge: bridge(Z1,Z2,Z3,Z4,Z5). ELEMENTS — name is "<Symbol><identifier>", Symbol a single uppercase letter (R, C, L, Q, W, T, O, K, I, S, X, N, G, H, D). Parameters auto-expand per element (e.g. Q1 → Qy1, Qa1). Common: R (Ω), C (F), L (H), Q=CPE (Qy, Qa), W=Warburg, T/O=finite diffusion, G=Gerischer, H/D=empirical. (s = jω = j·2π·f.) Examples: "Rs-Rct|Cdl", "Rs-(Rct-W)|Cdl" (Randles), "Rs-(Rct-W1)|Q1", "lad(R,Q,W)". For the full element catalog (every element's impedance + parameters, transmission-line options, bridge), call circuit_reference. On an invalid string, returns a clear parser error. Pure notation — no dataset needed.

Renders one or more EIS datasets as a chart and returns it for inline display on chart-capable hosts (Claude Desktop, Cowork, VS Code, AssistStudio, …), plus a token-light text summary per dataset. Pass a single id to plot one dataset, or several ids to overlay them as a comparison (each dataset gets its own color and legend entry) — e.g. to compare the datasets the user selected. kind: - nyquist (default): −Z″ vs Z′, equal aspect — read semicircles, Rs/Rp. - bode: |Z| and phase vs log frequency. - admittance: Y″ vs Y′ where Y = 1/Z. - residual: relative residual (Δreal/Δimag %) vs log frequency — a dataset-level fit-quality view; requires `analysis` and exactly one dataset. analysis: overlay a stored analysis reconstruction on the measured data (the same comparison the app's Data-Explorer offers). One of 'none' (default — measured only), 'zhit', 'kk', 'drt_tikhonov', 'drt_loewner', 'inductivefree' (the Loewner inductive-stray-removed spectrum vs the raw measured), or 'ecm'. For nyquist/bode/admittance each dataset that has that analysis gets its reconstruction drawn as a dashed line over its markers; run the analysis first (it is read from the dataset, not recomputed). 'residual' requires an analysis and renders (reconstructed − measured)/|Z|. In a comparison mode the measured side is the SNAPSHOT the analysis captured when it ran (for drt_loewner/inductivefree the de-embedded polarization / raw basis its fit lives on), not the live spectrum — so masking (raw-only) does not move it until you re-run the analysis. 'none' shows the live raw measured with masked points marked. The Plotly chart spec travels in structuredContent (zero model-token cost); the host renders it. On a text-only host the chart is omitted and only the summaries are returned — do not claim a chart was drawn in that case (check _meta.render_status). Requires a study_id (open_study) and dataset ids (open_study/list_tree). Charts reflect each dataset's se…

Reads a DC time-series file (charge/discharge, e.g. a BioLogic GCPL .mpr) into the session and returns a dc_id handle with a summary: source path and SHA-256, technique, acquisition start, row count, time and voltage ranges, every channel and marker (meaning, unit, origin, source column), quantities the file does not record, half cycles (rows, modes, direction, signed charge, voltage range), loops and steps. No row arrays are returned here -- use get_dc_curve or export_dc_data. USE WHEN: the user has charge/discharge (galvanostatic cycling) data, often next to EIS files. EIS files go through create_from_file / import_data instead. Supported: BioLogic .mpr GCPL (files with no frequency column, or only zero frequencies). Data is held in memory for this session only; it is not saved into a .zstudy. Voltages are exactly as recorded (never divided by a series-cell count). control/V/mA is a setpoint (current in CC rows, voltage in CV rows), split into current_setpoint / voltage_setpoint -- it is never a measured current. Reading the same unchanged file again returns the existing handle.

Removes a folder or dataset from a loaded study. Removing a folder removes everything inside it. The root and the default Inbox folder cannot be removed. Auto-saves the study — the removal persists to the .zstudy.

Renames a folder or dataset. The study root cannot be renamed. Auto-saves the study.

Renders a ZStudio circuit (CDC) in one representation: - infix: canonical CDC (e.g. "Rs-Rct|Cdl") - formula: impedance as a nested expression (1/(1/Rct + 1/Cdl) …) - symbolic: impedance with element transforms (1/(s*Cdl), 1/(Qy1*pow(s,Qa1)) …) - latex: LaTeX of the impedance formula - svg: schematic diagram as an SVG string Pure notation — no dataset needed.

Saves a loaded study to a .zstudy file (atomically), including any analysis results stored on its datasets. Path resolution: an explicit path if given, else the path the study was opened from / last saved to, else a new file in the working directory (the ZSTUDIO_WORKDIR environment variable, or a 'ZStudio' folder under the user's Documents) named after the study. The written path is returned. Note: studies auto-save to their bound path after each mutating tool call, so this is rarely needed for durability — use it mainly to "save as" to a new path, or to force a write when auto-save is disabled (ZSTUDIO_AUTOSAVE=off). Requires a study_id from open_study / new_study / create_from_file. If the bound file changed on disk outside this session (e.g. the user saved it from the ZStudio app), the save is refused so those changes are not silently overwritten — re-open the study to take the disk version, or pass force=true (ideally after confirming with the user) to overwrite.

Sets which dataset is the active one for the study (the default target the ZStudio app opens). Auto-saves the study.

Selects which data a dataset's downstream analyses (kk/drt/fit_ecm) and plots use: 'original' (raw measured) or 'zhit_corrected' (the Z-HIT reconstruction from a prior zhit call). 'zhit_corrected' requires that an applied Z-HIT correction exists on the dataset (zhit with apply=true, the default). Auto-saves the study.

Updates a dataset's editable properties — name and/or description. Only provided fields change. Auto-saves the study.

Masks (excludes) or unmasks measured points by frequency band, so analyses skip them — the EIS "trim the bad ends" operation. Give an inclusive band: "exclude below 0.1 Hz" is (freq_max_hz: 0.1), "exclude above 100 kHz" is (freq_min_hz: 100000), a band is both. At least one bound is required. Excluded points stay in the dataset (reversible — use clear_exclusions or is_excluded=false). Analyses use only non-excluded points, but stored analyses are NOT recomputed automatically: rerun kk / drt_tikhonov / drt_loewner / guess_ecm / fit_ecm after changing exclusions. The study auto-saves unless ZSTUDIO_AUTOSAVE=off. Requires a study_id and dataset_id.

Masks (excludes) or unmasks individual measured points by zero-based index — for picking off outliers. Get the indices from get_curve(include_excluded= true, source='original'), whose Index column matches these indices. Out-of-range and duplicate indices are ignored. Excluded points stay in the dataset (reversible). Analyses use only non-excluded points; stored analyses are NOT recomputed automatically — rerun kk / drt_* / guess_ecm / fit_ecm afterward. The study auto-saves unless ZSTUDIO_AUTOSAVE=off. For trimming a frequency tail prefer set_frequency_exclusions. Requires a study_id and dataset_id.

Updates study-level metadata. Only the fields you provide change; the rest are left as-is. Returns the updated study info. Auto-saves the study.

Forward-simulates an EIS spectrum FROM an equivalent circuit (the inverse of fit_ecm): evaluates the circuit (CDC + parameter values) over a log-spaced frequency grid and adds the synthetic spectrum to the study as a new dataset. Useful for "what does this circuit look like?", teaching, building reference/test data, or seeding a fit. Provide parameter values by name (see parse_circuit for the names/units); any omitted parameter uses its typical value. Returns the new dataset_id, the parameter values actually used, a token-light summary, and a Nyquist chart. The dataset behaves like any imported one — analyze it like measured data. Requires a study_id (open_study or new_study). Auto-saves the study.

Runs Z-HIT on a dataset's raw spectrum — the entry point of the analysis pipeline. Z-HIT reconstructs the impedance modulus from the phase via the Hilbert relation, giving a drift/artifact-corrected curve and a data-quality metric. Returns a token-light summary plus a chart overlaying the measured data (markers) with the Z-HIT reconstruction (dashed line). The summary describes how much the reconstruction changed the modulus — the size of the drift/artifact it removed: - residualMaxPct / residualMeanPct: |Z−Ẑ|/|Z| over the spectrum (%). - maxResidualAtHz: where the correction is largest (drift usually shows at low frequency, where the slow sweep is most time-variant). - driftBands: frequency ranges where the correction exceeds ~1%. - significant: true when the correction is large enough that downstream analysis should use the corrected data rather than the raw spectrum. When significant is true, call set_analysis_source('zhit_corrected') before kk / drt / fit_ecm so they run on the de-drifted curve; otherwise the raw data is fine. apply (default true): store the reconstruction as the dataset's corrected data — analyze + apply in one step, like the app's Apply button; a re-run REPLACES the stored correction (last run wins) and the study auto-saves. Pass apply=false to tune options non-destructively: the analysis result and summary are produced but the stored corrected data is left untouched — compare several option sets that way, then re-run the best one with apply=true. Tuning (all optional; defaults reproduce the app's auto behavior): the smoothing/interpolation/window methods default to 'auto' (the engine tries all and picks the best). Override only when auto misbehaves — e.g. pin smoothing_type='savitzkyGolay' with number_of_points / polynomial_order, or narrow the reconstruction window via window_center / window_width (log-f decades). Enable include_uncertainty for confidence bands. Requires a study_id (open_study) and…