ecNetSim_LTPS_NGS V10.7 & ecTrans V5.0 — User Manual
(AI-generated, may contain significant errors)

Author: Dr. Zhaoxiang Deng (USTC)
License: This software is licensed to the author only. Unauthorized distribution or commercial use is strictly prohibited.
Supported SPICE backends: PSpice/PSpice-For-TI/LTspice/QSPICE/Micro-Cap/NGSPICE (open source)
Supported plotting: Gnuplot (open source)

Table of Contents

1. Overview
2. System Requirements & Installation
3. Usage — Command Line
   • 3.1 ecNetSim 10.7
   • 3.2 ecTrans 5.0
4. Input File Format (.atn)
   • 4.1 General Rules
   • 4.2 Block-by-Block Reference
5. Output Files
6. Simulation Modes
7. Diffusion Geometries
8. Electrochemical Techniques Supported
9. Adsorption Support
10. ecTrans 5.0 — NGSPICE Integration & Post-Processing
11. Gnuplot Output & Concentration Profiles
12. Annotated Input File Examples
13. Error Messages Reference
14. Advanced Tips
15. Version History (selected)

1. Overview

ecNetSim converts electrochemical reaction schemes into SPICE netlists and executes transient circuit simulations to obtain cyclic voltammograms (CV), chronoamperograms (CA), and related results. Its core idea is the network model (ecNet): each mass-transport box becomes a resistor–capacitor network element, and charge-transfer kinetics become voltage-controlled current sources (G elements). The program reads a plain-text input file (.atn), generates a SPICE netlist (.sp, .cir, or .net), optionally runs NGSPICE or LTspice, reads the resulting .raw file, and plots via Gnuplot.

ecTrans is a companion program that accepts a previously generated (or user-modified) .sp or .spt netlist, drives NGSPICE in batch mode, parses the binary/ASCII .raw output, writes tabulated .out data files, generates a Gnuplot .gp script, and launches Gnuplot for interactive plotting — all in a single command-line invocation.

Capabilities summary

2. System Requirements & Installation

• OS: Windows XP, 7, 8, 10, 11 (64-bit recommended)
• Runtime: QB64 (already compiled into .exe)
• SPICE simulators (optional):
  • NGSPICE: place ngspice.exe in .\ngspice\ subdirectory relative to the .exe
  • LTspice: place ltspice.lnk shortcut in .\ltspice\ subdirectory
  • PSPICE: place pspice.lnk shortcut in .\pspice\ subdirectory
• Gnuplot (optional): place gnuplot.lnk in .\gnuplot\ subdirectory, or ensure gnuplot is on the system PATH

Directory structure example

C:\NETSIM\
  ecNetSimV10.x.exe     <- main executable (ecNetSim)
  ecTransV5.0.exe        <- companion NGSPICE runner
  ngspice\
    ngspice.exe          <- NGSPICE 64-bit binary
  ltspice\
    ltspice.lnk          <- shortcut to LTspice XVII
  pspice\
    pspice.lnk           <- shortcut to PSpice
  gnuplot\
    gnuplot.lnk          <- shortcut to Gnuplot
  input.atn              <- your input file

Using a .bat wrapper

To call the program from any directory (so the input file path is resolved correctly), use the provided batch wrapper:

@"C:\NETSIM\ecNetSimV10.x.exe" "%CD%\%~1"

Call as: ecnetsim myfile.atn

3. Usage — Command Line

3.1 ecNetSim 10.7

ecNetSimV10.x.exe [FILENAME]
ecNetSimV10.x.exe /?

• FILENAME — path to the .atn input file (absolute or relative).
  If omitted, defaults to input.atn in the current working directory.
• /? — print usage hint and exit.
• The program also accepts .net, .cir, or .sp files directly; it will attempt to extract the embedded .atn content (if the netlist was generated with the sp+/net+/cir+ option).

3.2 ecTrans 5.0

ecTransV5.0.exe  <FILENAME>.sp
ecTransV5.0.exe  <FILENAME>.spt

• FILENAME — path to a .sp or .spt netlist file. This file must have been generated by ecNetSim. ecTrans reads the netlist directly; it does NOT parse .atn files. The + suffix on netlist options (sp+, cir+, net+) is NOT required for ecTrans.
• No argument → program exits with an error message.
• ecTrans does NOT accept .atn files directly — it only processes pre-generated netlists.

4. Input File Format (.atn)

4.1 General Rules

1. The file consists of alternating prompt lines (in square brackets, e.g. [Number of Reaction-diffusion Species(no period)]) and data lines.
2. Do not modify prompt lines. The program validates them exactly; any change causes a fatal error.
3. Data lines follow immediately after each prompt line. Blank lines and * memo lines between prompt and data are silently skipped.
4. Lines starting with * are treated as memo/comment lines and are silently skipped everywhere.
5. Whitespace: leading and trailing spaces are stripped automatically. TAB characters are forbidden and will trigger an error.
6. Terminators:
   • Sections that end with (with period) in the prompt use . (period) as a section terminator and ; as a record separator.
   • Sections that end with (no period) use a single value on one line; no terminator needed.
7. Scientific notation: values like 1e-5, 1E-5, 1.5e-10 are supported everywhere. The built-in SafeVal() function correctly handles negative exponents that QB64's native Val() misparses.
8. The file ends with the line [END].
9. Appended input: If using sp+/cir+/net+ as [Netlist] option, input (.atn) content is appended to the end of the netlist, allowing re-run from the netlist file directly with ecNetSim. Note: ecTrans only works with netlist files and does NOT require the + suffix; the + suffix is an ecNetSim-internal feature for embedding .atn content.
10. Prompt-line validation (sqerr): The program counts how many prompt lines are matched. At the end, it verifies the count against expected values (15, 16, 17, or 18 depending on which optional sections are present). A mismatch produces the error *"You must have changed the prompt lines in the input file!"*.

4.2 Block-by-Block Reference

[Method(CV/CA: Cyclic Voltammetry/ChronoAmperometry)(no period)]

Data line: CV or CA

If omitted or invalid, defaults to CV.

[Number of Reaction-diffusion Species(no period)]

Data line: a positive integer N (≥ 1).

Defines the total number of species that participate in diffusion and/or adsorption. Must be set before the ETR/HCR blocks. Species are referenced by index 1 … N throughout the file.

Electron Transfer Reactions (ETR)

There are four variant prompt lines for ETR — the program accepts any of them:

1. [Electron Transfer Reactions|E0'(V)|alpha|alpha2|na|k0(cm/s or s^-1 for SF)(with period)]
2. [ET Reactions|E0'(V)|alpha|alpha2|na|k0(cm/s or s^-1 for SF)(prefix @/@@: dependent/independent ETRs of adsorbates)(with period)]
3. [Electron Transfer Reactions|E0'(V)|alpha|na|k0(cm/s or s^-1 for SF)(with period)]
4. [ET Reactions|E0'(V)|alpha|na|k0(cm/s or s^-1 for SF)(prefix @/@@: dependent/independent ETRs of adsorbates)(with period)]

The number of ETR reactions m is NOT specified by the user. The parser reads reaction lines one by one after the prompt. If the first data line starts with [, then m = 0 (no ETR). Otherwise, reactions are read until a line ending in . (last reaction) is encountered.

NOTE — Minimal input required for pure chemical kinetics mode (m = 0, no ETR, HCR present):

• [Method]: must be set to CA
• [Number of Reaction-diffusion Species]: total number of species participating in HCR
• [Homogeneous Chemical Reactions|…]: HCR definitions (one reaction per line)
• [Experimental Parameters|…]: only the time parameter is meaningful; all other parameters may be set to 0
• [Simulation Parameters ]: only the time-interval parameter is meaningful; all other parameters may be set to 0
• [Initial Concentrations|…]: initial concentrations for all species
• Output (optional): use CP<n>- and CP<n>_ to export concentration profiles for specific species

Each ETR occupies one line ending in ; (more reactions to follow) or . (last reaction):

OxSpeciesNum[a]+|-[n]e<->RedSpeciesNum[a]|E0'|alpha[|alpha2]|na|k0;

Fields (pipe-separated):

Adsorbed species ETR prefix (prompts 2 & 4 only):

When ALL species in the ETR are adsorbed (all marked with trailing a, e.g. 1a+e<->2a), prefix the line with @ or @@ to indicate an adsorbate ETR. The @/@@ prefix represents electrochemical or chemical conversion between adsorbed states on the electrode surface. Both modes use surface concentration nodes and the same k⁰ normalization (k0_nondim = k⁰ × τ); the difference is only in the formal potential treatment:

• @ (dependent adsorbate ETR): The formal potential specified in the input is the standard (bulk-solution) E⁰. The program automatically corrects it for the adsorption free-energy difference: E⁰_corrected = E⁰_input − (RT/nF)·ln(β_Ox/β_Red) This mode is used when the adsorbed ETR is thermodynamically coupled to the solution E⁰, e.g. the species adsorb with different affinities and the E⁰ must shift accordingly. The correction requires valid β values in the [Adsorption Coefficients] block for both the oxidized and reduced adsorbates.

• @@ (independent adsorbate ETR): The formal potential specified in the input is the actual surface E⁰. No thermodynamic correction is applied. Use this mode when the E⁰ is measured or defined directly for the adsorbed phase and does not depend on bulk-solution β values.

Example — @ (dependent) adsorbate ETR:

@1a+e<->2a|0|0.5|1|1e8.

E⁰_input = 0 V. If β₁ = 100 and β₂ = 400, then E⁰_corrected = 0 − (RT/F)·ln(100/400) = +0.036 V (at 298 K).

Example — @@ (independent) adsorbate ETR:

@@1a+1e<->2a|0.36|0.5|1|1e8.

E⁰ = 0.36 V is used directly as the surface formal potential. No β-dependent correction.

Example — single-step 1e reduction (new format with alpha2):

1+1e<->2|0.0|0.5|0.5|1|0.01.

Species 1 (Ox) + 1 electron → Species 2 (Red), E⁰' = 0.0 V, α_c = 0.5, α_a = 0.5, na = 1, k⁰ = 0.01 cm/s.

Example — single-step 1e oxidation (legacy format without alpha2):

1-e<->2|0.49|0.5|1|1e6.

Species 1 (Red) − 1 electron → Species 2 (Ox), E⁰' = 0.49 V, α_c = 0.5, na = 1, k⁰ = 1×10⁶ cm/s.

Example — adsorbate ETR with kinetic adsorption:

@1a+e<->2a|0|0.5|1|1e8.

Dependent adsorbate ETR: adsorbed species 1 → adsorbed species 2, E⁰ = 0 V, k⁰ = 1×10⁸ s⁻¹.

Example — two sequential ETRs (EEE mechanism, legacy format):

1-e<->2|0.49|0.5|1|1e6;
2-e<->3|1.15|0.5|1|1e6.

If no ETR reactions are desired, the prompt line must still be present, but the next line can be another prompt line starting with [; the program will then set m = 0.

Homogeneous Chemical Reactions (HCR)

Two variant prompt lines:

1. [Homogeneous Chemical Reactions|kfc|kbc(with period)]
2. [Homogeneous Chemical Reactions|kfc|kbc(prefix @: reactions of adsorbates)(with period)]

The number of HCR reactions mc is NOT specified by the user. If the first data line starts with [ and m <> 0, then mc = 0. If m = 0 and the data line starts with [, the program reports an error.

Each HCR reaction occupies one line ending in ; or .:

ReactantSpeciesList<->|-->ProductSpeciesList|kfc|kbc;

Fields:

Adsorbed HCR prefix (prompt 2 only): @ before a reaction line denotes an adsorbate reaction.

Example — 2nd-order dimerization (irreversible):

1+1-->0|1e4|0.

Two molecules of species 1 → product leaves system, kf = 1×10⁴ mM⁻¹s⁻¹, irreversible.

Example — EC mechanism (E followed by C): ETR block: 1-e<->2|0.0|0.5|1|0.1. HCR block: 2<->3|100|1.

Example — multi-species reversible HCR with adsorbates:

2<->3|1e10|0;
@2a<->3a|1e12|0;
2+5a<->1+6|4.3e2|1e5.

[Diffusion Type(L/S/C/RDE/FD/SF: Linear/Spherical/Cylindrical/Rotational Disk/Finite Diffusion/SurFace)(no period)]

Conditional: This section is only processed when m <> 0.

Data line: one of:

Default if omitted (next line starts with [): L.

[Area(cm^2)/Radius(um)/Radius,Length(cm)/Angular Velocity(rad/s),Kinematic Viscosity(cm^2/s),Area/Area,Thickness(cm)/Area(no period)]

Conditional: This section is only processed when m <> 0.

Data line format depends on diffusion type:

All values must be positive.

[Experimental: cycles,Ei(V),Es(V),Et(V),v(V/s) or Time(s) for CA,Temper(C.D.)(no period)]

or the variant with rest time:

[Experimental: cycles,Ei(V),Es(V),Et(V),v(V/s) or Time(s) for CA,Rest time(s),Temper(C.D.)(no period)]

Data line: cycles,Ei,Es,Et,v[,t_rest],temperature

Notes:

• For CV: the program sweeps Ei → Es (forward scan) → Et (reverse scan), and this full cycle is repeated cycles times. If Et = Es, the reverse scan has zero amplitude (useful for LSV).
• For CA: the potential is stepped from Ei to Es (approximately 1/10⁶ of the total simulation time in dimensionless units, excluding the rest time), and held at Es. For multi-cycle CA, the potential alternates between Es and Et each half-cycle.
• Es = Ei is allowed (special case).

Example — CV, 2 cycles, ±0.5 V window, 0.1 V/s, 25 °C:

2,-0.5,0.5,-0.5,0.1,25

Example — CA with rest time (empty for no rest):

1,1.2,-0.5,1.2,1e4,,25.0

[Simulation: boxnum,beta,dE(mV) or dt(s) for CA(no period)]

or the variant with binary reading limit:

[Simulation: boxnum,beta,binary reading limit,dE(mV) or dt(s) for CA(no period)]

Data line: boxnum,beta[,bin_limit],dE

Example:

30,0.5,,1

30 boxes, β = 0.5, bin_limit = default (≈ 3.8 MB), 1 mV step.

[IR drop: Ru(ohm),Cdl(F)(no period)]

Conditional: This section is only processed when m <> 0. If the data line starts with [, both default to 0.

Data line: Ru,Cdl

Both must be ≥ 0.

Example:

50,1e-6

[Initial Concentrations(mM or mol/cm^2 for SF)(with period)]

Assigns initial concentrations to all N species. Format:

SpeciesNum[,SpeciesNum2,...][or RangeStart-RangeEnd]|value;
...

• Values are in mM (mmol/L) for diffusing species, or mol/cm² for SF surface species.
• Species numbers can be listed individually (1,3,5) or as a range (1-5), separated by commas.
• The species list and value are separated by |.
• Each assignment line ends with ; (more to follow) or . (last).
• At least one species must have a non-zero concentration; otherwise the program aborts.
• Concentrations must be ≥ 0.

Example — 3 species, species 1 at 1 mM, species 2 and 3 at 0 mM:

1|1;
2,3|0.

Example — species 1 only, with scientific notation:

1|0.1e0;
2-6|0e0.

[Diffusion Coefficients(cm^2/s)(with period)]

Conditional: This section is only processed when m <> 0 and diffusion type is not SF. Skipped automatically when m = 0 or SF.

Same format as concentrations. All values must be > 0.

Example:

1-3|1e-5.

All three species have D = 1×10⁻⁵ cm²/s.

[Saturated Surface Excesses(mol/cm^2 for adsorbates)(with period)]

Conditional: This section is only processed when m <> 0. Can be omitted entirely; if present but the first data line starts with [, it is silently skipped.

Required only when adsorption is enabled (i.e., at least one species index ends with a in the ETR/HCR block). Assigns the Langmuir saturation surface excess Γ_max for each adsorbate.

Same format as concentrations. Values must be > 0 for adsorbates.

Example:

1-2|1e-10;
3|1e-10.

[Adsorption Coefficients(mM^-1 for adsorbates) or Rate Constants(kads,kdes)(with period)]

or (equilibrium-only variant):

[Adsorption Coefficients(mM^-1 for adsorbates)(with period)]

Conditional: This section is only processed when m <> 0. Can be omitted entirely; if present but the first data line starts with [, it is silently skipped.

Same format. Two modes per species:

Mode 1 — Equilibrium (Langmuir): Single β value per species:

1|1e2;
2|0.4.

Sets ads_kin = 0 (equilibrium). The surface excess follows the instantaneous Langmuir isotherm: Γ_j = β_j · c_j(0) · Γ_sat,j / (1 + Σ_k β_k · c_k(0)).

Mode 2 — Kinetic (kads, kdes): Comma-separated pair:

1|3e2,1.2e4;

Sets kf_ads and kb_ads individually (also accepted as kads and kdes — both labels are synonymous); β is computed as kf/kb internally. When all adsorbate species use this mode, the simulation uses kinetic Langmuir ODEs: dΓ_j/dt = k_f,j · c_j(0) · (Γ_sat,j − Σ_k Γ_k) − k_b,j · Γ_j.

Mixed input (Mode 1 + Mode 2 on the same block): Allowed. When some species are given single β values and others are given kads,kdes pairs, the program treats the kads,kdes entries by computing β = kf/kb and falls back to equilibrium adsorption for all species. A warning is printed:

<Warning!> Adsorption in equilibrium is assumed in simulation due to lack of required kads and kdes

Example of mixed input (equilibrium result despite species 1 having kinetic constants):

1|3e2,1.2e4;   ← kf/kb → β = 0.025 internally, but equilibrium mode still used
2|0.4.         ← direct β, equilibrium mode

Non-competitive adsorption mode: By default all adsorbate species compete for the same surface sites (competitive Langmuir, comp_ads = 1). To switch to non-competitive (independent-site) Langmuir (comp_ads = 0), prefix any species number in the data block with a minus sign (-):

-1|1e2;
2|0.4.

When any line in this block carries the - prefix, comp_ads is set to 0 for the entire block. The isotherm and vacancy equations change as follows:

Each species adsorbs independently onto its own set of sites, without competing with other adsorbates. This also affects pre-adsorption equilibrium initialization when + is used.

Pre-adsorption equilibrium marker: Append + before the terminator (; or .) in the value field to enable pre-adsorption equilibrium (all adsorbates initialized at Langmuir equilibrium):

1|3e2,1.2e4+;

Current Output / Simulation Output

These are two separate prompt lines (only ONE may appear in a given .atn file; they are mutually exclusive and share the same handler):

1. [Current Output(CF/DF:Current Function/DeFault)(no period)]
2. [Simulation Output(CF/DF/CPn:Current Function/DeFault/Concentration Profle)(no period)]

Conditional: Both are only processed when m <> 0. If the data line starts with [, defaults to DF.

Data line (for either prompt):

If the data line is invalid or unrecognized, defaults to DF.

[Dimensionless Simulation Layer: Lmax(no period)]

or the variant with natural convection:

[Dimensionless Natural Convection Layer and Simulation Layer: delta_Convec,Lmax(no period)]

Conditional: Both are only processed when m <> 0. The two variants are mutually exclusive — only one appears in a given .atn file.

Variant 1 — Lmax only: | Input | Meaning | |-------|---------| | 6 (or any number) | Explicit dimensionless diffusion layer thickness. Default for linear/spherical/cylindrical = 6. | | 3delta_max | RDE: 3× the Levich diffusion layer. Any multiplier is allowed. | | (blank or next line starts with [) | Program auto-selects: 6 for L/S/C; 3*delta_max for RDE; length/√(D_max·τ) for FD. |

Variant 2 — Both natural convection and Lmax: Two comma-separated values: delta_Convec,Lmax

• delta_Convec = dimensionless natural convection layer thickness. Use empty or NC to disable. Examples: 0.1 (enabled), `` (empty, disabled)
• Lmax = same rules as Variant 1.

Example:

0.06546,6

[Netlist: net/cir/sp]

Data line: net, cir, sp, net+, cir+, or sp+.

Default: sp.

When + is used, output files share the same base name and directory as the input file. Without +, files are written as autonet.* in the current working directory.

[Do you want to run the simulation immediately(Y/N)?(no period)]

Data line: Y, N, Y+, or N+.

Recommendation: Use N+ when you plan to post-process with ecTrans 4.0, or when you want to manually edit the netlist before simulating.

[END]

Mandatory last line of the input file.

5. Output Files

5.1 The .atn output file and the net+/sp+/cir+ option

When you append + to the netlist format (net+, sp+, or cir+) at the [Netlist: net/cir/sp] prompt, ecNetSim sets an internal flag (atn_out$ = "+") and changes its output behavior:

1. Netlist file — input content appended inside

The program appends the entire .atn input file after a delimiter block at the end of the generated netlist:

* INPUT SOURCE (for reference, not part of netlist)
* ==================================================
[Number of Reaction-diffusion Species(no period)]
5
...
[END]

This embedded copy allows ecNetSim to re-run the simulation directly from the netlist file, without requiring the original .atn file to be present.

2. Standalone .atn output file

A separate .atn file is also written to the output directory (outputDir$ + file_name$ + ".atn"), containing the same content. This gives you a clean, standalone copy of the input that produced the netlist.

3. Re-running from the netlist file

When you later run:

ecNetSimV10.x.exe myfile.sp

...the program detects the * INPUT SOURCE... marker, extracts the embedded .atn content, re-parses it, and regenerates the netlist. This is functionally equivalent to re-running with the original .atn file.

4. Without the + suffix (net / sp / cir)

The .atn content is not appended to the netlist. The netlist file contains only SPICE netlist statements. To re-run the simulation, you must keep the original .atn file separately.

Note: ecTrans does NOT use the + suffix. It reads the netlist file directly and does not need the embedded .atn content. The + suffix is an ecNetSim-only feature for convenience when iterating on input files.

6. Simulation Modes

Cyclic Voltammetry (CV)

The applied potential waveform is:

Ei → Es (first half-scan) → Et → Es (second half-scan) → ... × cycles

The potential step dE (mV) controls the time resolution. Smaller dE = finer resolution but slower.

Chronoamperometry (CA)

The potential is stepped from Ei to Es (near-instantaneously) and held at Es. The "scan rate" field in the input file is reinterpreted as total time τ (s). dE is reinterpreted as the time step dt (s). For multi-cycle CA, the potential alternates between Es and Et each half-cycle.

Advanced Waveforms (SWV, DPV, ACV, EIS)

ecNetSim generates the CV/CA waveform automatically. For other waveforms (SWV, DPV, ACV, EIS), commented-out SPICE source lines are inserted into the netlist as templates. The user manually un-comments the relevant lines:

• ACV: uncomment Vsin_Eapp1 (SIN source), comment out Vdc0_Eapp1.
• SCV: uncomment VSawtooth_Eapp1, comment out Vdc0_Eapp1.
• SWV (Osteryoung): uncomment VSawtooth_Eapp1 and Vpulse_Eapp_sum, comment out Vdc0_Eapp1 and Vdc0_Eapp_sum.
• SWV (Barker/ramped): uncomment Vpulse_Eapp_sum, comment out Vdc0_Eapp_sum. The existing CV ramp is used as the base waveform.
• DPV: uncomment Vsawtooth_Eapp1 and Vdpv_Eapp_sum, comment out Vdc0_Eapp1 and Vdc0_Eapp_sum.
• EIS: uncomment .include PWL_white_noise.txt, comment out Vdc0_Eapp1.

7. Diffusion Geometries

Linear (L)

Semi-infinite 1D diffusion to a planar electrode. Input: electrode area A (cm²).

Spherical (S)

Semi-infinite spherical diffusion to a microelectrode. Input: electrode radius r (μm).

Cylindrical (C)

Semi-infinite cylindrical diffusion. Input: radius (cm), length (cm).

Rotational Disk Electrode (RDE)

Uses the Levich–Koutecký model. Input: angular velocity ω (rad/s), kinematic viscosity ν (cm²/s), electrode area A (cm²).
Default Lmax = 3·δ_Levich.

Finite Diffusion (FD)

Thin-layer cell with a reflective boundary at x = L. Input: area A (cm²), layer thickness L (cm).

Surface-confined (SF)

No spatial diffusion. All species are surface-confined (thin-film or adsorbed monolayer).
Input: electrode area A (cm²).
Rate constant k⁰ has units s⁻¹.
Concentration has units mol/cm².
CF output is not available for SF.

8. Electrochemical Techniques Supported

9. Adsorption Support

To enable adsorption, append a to a species number in the ETR or HCR reaction formula (e.g. 1a means species 1 is adsorbed). The program then expects:

• [Saturated Surface Excesses...] block — Γ_max (mol/cm²) for each adsorbed species.
• [Adsorption Coefficients...] block — β (mM⁻¹) for equilibrium, or kads/kdes for kinetic adsorption.

Equilibrium Langmuir Adsorption

The surface excess is determined by the instantaneous bulk concentration at x = 0.

Competitive (default, comp_ads = 1): All adsorbates share the same surface sites:

Γ_j = β_j · c_j(0) · Γ_sat,j / (1 + Σ_k β_k · c_k(0))

Non-competitive (comp_ads = 0): Each species adsorbs onto independent sites (triggered by a - prefix; see Section 4.2):

Γ_j = β_j · c_j(0) · Γ_sat,j / (1 + β_j · c_j(0))

This is the default adsorption mode (ads_kin = 0). It is activated unless all adsorbate species in the block are given kads,kdes pairs (see Kinetic mode below).

Kinetic Langmuir Adsorption

The surface excess evolves dynamically.

Competitive (comp_ads = 1, default):

dΓ_j/dt = k_f,j · c_j(0) · (Γ_sat,j − Σ_k Γ_k) − k_b,j · Γ_j

Non-competitive (comp_ads = 0):

dΓ_j/dt = k_f,j · c_j(0) · (Γ_sat,j − Γ_j) − k_b,j · Γ_j

Activated only when all adsorbate species in the block are given kads,kdes pairs (ads_kin = 1). If any species uses a single β value (Mode 1), ads_kin is reset to 0 and the entire block falls back to equilibrium adsorption (see Mixed Input below).

Mixed Input

The [Adsorption Coefficients] block permits mixing Mode 1 (β) and Mode 2 (kads,kdes) entries for different species in the same block. When this occurs, the kads,kdes pairs are internally converted to β = kf/kb, and the simulation proceeds with equilibrium adsorption for all species. A runtime warning is emitted:

<Warning!> Adsorption in equilibrium is assumed in simulation due to lack of required kads and kdes

Adsorbate ETR

Adsorbate ETRs are defined by prefixing the reaction line with @ or @@ and using species numbers with trailing a (e.g. 1a, 2a). The @/@@ prefix determines whether the formal potential is corrected for adsorption free energy.

@ (dependent adsorbate ETR): The input E⁰ is the standard (bulk-solution) formal potential. The program applies the Nernst correction: E⁰_corrected = E⁰_input − (RT/nF)·ln(β_Ox/β_Red). This requires β values for both oxidized and reduced adsorbates in the [Adsorption Coefficients] block. Use when the adsorbed ETR is thermodynamically coupled to solution-phase E⁰.

@@ (independent adsorbate ETR): The input E⁰ is the surface formal potential and is used directly without correction. Use when the E⁰ is defined for the adsorbed phase and does not depend on bulk β values.

Both modes share identical SPICE netlist structure: surface concentration nodes (az0_5), rate normalization (k0_nondim = k⁰ × τ), and Butler-Volmer expression. The only difference is the E⁰ treatment.

Pre-adsorption equilibrium

Append + before the terminator in the Adsorption Coefficients value to initialize all adsorbates at Langmuir equilibrium before the simulation starts. The initialization formula follows the active comp_ads setting (competitive or non-competitive):

1|3e2,1.2e4+;

Both electrochemically active (participating in ETR) and inactive (participating in HCR only) adsorbed species are supported.

10. ecTrans 5.0 — NGSPICE Integration & Post-Processing

10.1 How ecTrans works

ecTrans automates the entire NGSPICE → raw data → plot pipeline:

1. Parse command-line path → extract directory and base filename
2. Delete any existing .raw, .out, _xyz.out, _3d.out files for this name
3. Call NGSPICE in batch mode:
   Shell ".\ngspice\ngspice -b <file>.sp -r <file>.raw -o <file>.log"
4. Check .raw file exists:
   If NOT found → "Simulation failed!" → exit
   If found:
     a. Call raw_reader → parse binary/ASCII .raw data
     b. Read metadata comment from .sp file:
        "*info for data plotting by transient:"
        Extracts: method, difftype, Ru, Cdl, conc_start, cp_yes,
                 cp_ads_yes, tao, t_rest, Cmax, Dmax, Lmax
     c. Write .gp Gnuplot script (multiple plot windows)
     d. If CP data present: call data_3d → write _3d.out
     e. Call gnuplot → display interactive plots

10.2 Raw file format

NGSPICE outputs both binary and ASCII .raw files. ecTrans auto-detects the format by searching for Binary: in the header. For binary files, variables are stored as 64-bit doubles. The first variable is always time (time); subsequent variables are node voltages (V(node)).

10.3 Metadata in .sp file

When ecNetSim generates the netlist, it always appends a metadata comment block that ecTrans reads. The sp+/cir+/net+ suffix only controls whether the .atn input content is also appended; the metadata block (*info for data plotting by transient:) is always present regardless of the + suffix.

*info for data plotting by transient:
*method: CV
*difftype: L
*Ru: 0
*Cdl: 0
...

This allows ecTrans to configure its post-processing automatically without requiring additional user input.

10.4 Running ecTrans manually

ecTransV5.0.exe myfile.sp

Or with NGSPICE directly (without ecTrans):

ngspice -b myfile.sp -r myfile.raw -o myfile.log
gnuplot myfile.gp

Note: When running NGSPICE manually (without ecTrans), the .gp script must be manually created or modified to match your simulation parameters, as ecTrans normally generates this file automatically.

11. Gnuplot Output & Concentration Profiles

Standard plots generated (CV mode)

Standard plots generated (CA mode)

.out file columns (CV, Ru = 0, Cdl = 0)

Additional columns appear when Ru ≠ 0 or Cdl ≠ 0 (Cdl current component and IR-corrected potential).

Concentration profile option

Set [Simulation Output] or [Current Output] to CP<n> where <n> is the species number (1, 2, ...).

Use CP<n>+ to also output _xyz.out (t, x, c format, suitable for external post-processing).

Use CP<n>a for adsorbed species surface excess profiles.

Use CP<n>- to plot the surface concentration of species <n> (c at x = 0) as a function of time instead of the full heatmap. This is useful for surface-dominated processes or when only the boundary concentration evolution is needed. Not applicable to SF.

Use CP<n>_ to plot the initial spatial concentration profile of species <n> at t = 0 (c vs x) instead of the time-evolved heatmap. This also triggers _xyz.out output. Not applicable to SF.

12. Annotated Input File Examples

Example 1: Reversible CV, linear diffusion (E + C mechanism)

Below is an E + C mechanism (1e⁻ reduction followed by irreversible chemical disappearance), 2 species, linear diffusion, 2 CV cycles. This follows the same format as the reference manual for v9.6.

[Method(CV/CA: Cyclic Voltammetry/ChronoAmperometry)(no period)]
CV

[Number of Reaction-diffusion Species(no period)]
2

[Electron Transfer Reactions|E0(V)|arfa|arfa2|na|k0(cm/s or s^-1 for SF)(with period)]
1+1e<->2|0.0|0.5|0.5|1|0.01.

[Homogeneous Chemical Reactions|kfc|kbc(with period)]
2<->0|100|0.

[Diffusion Type(L/S/C/RDE/FD/SF: Linear/Spherical/Cylindrical/Rotational Disk/Finite Diffusion/SurFace)(no period)]
L

[Area(cm^2)/Radius(um)/Radius,Length(cm)/Angular Velocity(rad/s),Kinematic Viscosity(cm^2/s),Area/Area,Thickness(cm)/Area(no period)]
0.0314

[Experimental: cycles,Ei(V),Es(V),Et(V),v(V/s) or Time(s) for CA,Temper(C.D.)(no period)]
2,-0.5,0.5,-0.5,0.1,25

[Simulation: boxnum,beta,dE(mV) or dt(s) for CA(no period)]
100,0.4,2

[IR drop: Ru(ohm),Cdl(F)(no period)]
0,0

[Initial Concentrations(mM or mol/cm^2 for SF)(with period)]
1|1.0;
2|0.

[Diffusion Coefficients(cm^2/s)(with period)]
1,2|5e-6.

[Current Output(CF/DF:Current Function/DeFault)(no period)]
DF

[Dimensionless Simulation Layer: Lmax(no period)]
6

[Netlist: net/cir/sp]
sp+

[Do you want to run the simulation immediately(Y/N)?(no period)]
Y+

[END]

Example 2: Adsorption with kinetic model, solution + adsorbate ETRs

This example (adapted from EC_CV_ADS_SF_ETR_HCR2.atn) demonstrates:

• 3 species with both solution and adsorbate ETRs
• Kinetic adsorption with pre-adsorption equilibrium
• Adsorbate HCR reactions
• Concentration profile output

*for ecNetSim v10.2 and higher.
[Method(CV/CA: Cyclic Voltammetry/ChronoAmperometry)(no period)]
CV
[Number of Reaction-diffusion Species(no period)]
3
[ET Reactions|E0(V)|arfa|na|k0(cm/s or s^-1 for SF)(prefix @/@@: dependent/independent ETRs of adsorbates)(with period)]
1+e<->2|0|0.5|1|1;
@1a+e<->2a|0|0.5|1|1e8.
[Homogeneous Chemical Reactions|kfc|kbc(prefix @: reactions of adsorbates)(with period)]
2<->3|1e10|0;
@2a<->3a|1e12|0.
[Diffusion Type(L/S/C/RDE/FD/SF: Linear/Spherical/Cylindrical/Rotational Disk/Finite Diffusion/SurFace)(no period)]
L
[Area(cm^2)/Radius(um)/Radius,Length(cm)/Angular Velocity(rad/s),Kinematic Viscosity(cm^2/s),Area/Area,Thickness(cm)/Area(no period)]
0.196
[Experimental: cycles,Ei(V),Es(V),Et(V),v(V/s) or Time(s) for CA,Rest time(s),Temper(C.D.)(no period)]
1,1.2,-0.5,1.2,1e4,,25.0
[Simulation: boxnum,beta,binary reading limit,dE(mV) or dt(s) for CA(no period)]
30,0.5,,1
[IR drop: Ru(ohm),Cdl(F)(no period)]
0,0
[Initial Concentrations(mM or mol/cm^2 for SF)(with period)]
1|1;
2,3|0.
[Diffusion Coefficients(cm^2/s)(with period)]
1-3|1e-5.
[Saturated Surface Excesses(mol/cm^2 for adsorbates)(with period)]
1-2|1e-10;
3|1e-10.
[Adsorption Coefficients(mM^-1 for adsorbates) or Rate Constants(kads,kdes)(with period)]
1|3e2,1.2e4+;
2|1e2,0.1;
3|3e2,1.2e4.
[Simulation Output(CF/DF/CPn:Current Function/DeFault/Concentration Profle)(no period)]
*CP1
[Dimensionless Natural Convection Layer and Simulation Layer: delta_Convec,Lmax(no period)]
*0.06546,6
[Netlist: net/cir/sp]
sp
[Do you want to run the simulation immediately(Y/N)?(no period)]
Y+
[END]

Notes on this example:

• @ prefix on ETR line 2: dependent adsorbate ETR. E0 = 0 V will be automatically corrected to E0 − (RT/nF)·ln(β_1/β_2).
• @ prefix on HCR line 2: ALL species in that HCR are adsorbates, and the chemical reaction occurs on the electrode surface (not in solution). Only line 2 has the @ prefix in this example.
• + before ; in adsorption coefficient: enables pre-adsorption equilibrium. Any species line can have the + marker; only one declaration is needed (no need to repeat on multiple lines).
• * comment lines: the *CP1 and *0.06546,6 are commented out; uncomment to enable.
• [Saturated Surface Excesses] and [Adsorption Coefficients] are both present → sqerr = 18.

Example 3: Multi-step ETR with adsorption (fence mechanism)

This example (adapted from fence_set_ADS.atn) demonstrates a complex electrochemical scheme with 4 sequential ETRs, HCR cross-coupling, and equilibrium adsorption.

[Method(CV/CA: Cyclic Voltammetry/ChronoAmperometry)(no period)]
CV
[Number of Reaction-diffusion Species(no period)]
6
[Electron Transfer Reactions|E0(V)|arfa|na|k0(cm/s or s^-1 for SF)(with period)]
1-e<->2|0.49|0.5|1|1e6;
2-e<->3|1.15|0.5|1|1e6;
4-e<->5|0.050|0.5|1|1e6;
5-e<->6|0.63|0.5|1|1e6.
[Homogeneous Chemical Reactions|kfc|kbc(with period)]
4-->1|600|0;
2a-->5|290|0;
3-->6|5e3|0;
2+5a<->1+6|4.3e2|1e5.
[Diffusion Type(L/S/C/RDE/FD/SF: Linear/Spherical/Cylindrical/Rotational Disk/Finite Diffusion/SurFace)(no period)]
L
[Area(cm^2)/Radius(um)/Radius,Length(cm)/Angular Velocity(rad/s),Kinematic Viscosity(cm^2/s),Area/Area,Thickness(cm)/Area(no period)]
0.000314
[Experimental: cycles,Ei(V),Es(V),Et(V),v(V/s) or Time(s) for CA,Temper(C.D.)(no period)]
1,-0.4,1.4,-0.4,200,25.0
[Simulation: boxnum,beta,dE(mV) or dt(s) for CA(no period)]
30,0.5,1
[IR drop: Ru(ohm),Cdl(F)(no period)]
0,0
[Initial Concentrations(mM or mol/cm^2 for SF)(with period)]
1|0.1e0;
2-6|0e0.
[Diffusion Coefficients(cm^2/s)(with period)]
1-6|1.0e-05.
[Saturated Surface Excesses(mol/cm^2 for adsorbates)(with period)]
2|6.25e-10;
5|10e-10.
[Adsorption Coefficients(mM^-1 for adsorbates)(with period)]
2|0.4;
5|1.0.
[Current Output(CF/DF:Current Function/DeFault)(no period)]
[Dimensionless Simulation Layer: Lmax(no period)]
[Netlist: net/cir/sp]
sp
[Do you want to run the simulation immediately(Y/N)?(no period)]
Y+
[END]

Notes on this example:

• 4 oxidation ETRs (all use -e notation).
• HCR reactions use --> for irreversible and <-> for reversible.
• Adsorbed species 2a and 5a participate in HCR through their dissolved state. The a suffix in non-@ HCR lines indicates that the species is also involved in adsorption elsewhere, but the HCR itself involves the dissolved form. For reactions between adsorbed species on the electrode surface, use the @ prefix (see HCR @ prefix description).
• [Current Output] and [Dimensionless Simulation Layer] data lines are omitted (defaults applied).
• Only [Saturated Surface Excesses] present (no [Adsorption Coefficients] variant with kads/kdes) → equilibrium adsorption.

13. Error Messages Reference

14. Advanced Tips

Re-running from a netlist file with ecNetSim

If you used sp+, the .sp file contains the embedded .atn input after the netlist. You can pass the .sp file directly:

ecNetSimV10.x.exe myfile.sp

The program extracts the .atn content, re-parses it, and regenerates the netlist.

Re-running with ecTrans (recommended workflow)

ecNetSimV10.x.exe myfile.atn    (Netlist=sp, Run=N)
ecTransV5.0.exe myfile.sp       (NGSPICE + raw parsing + Gnuplot)

This two-step approach allows you to inspect or edit the .sp netlist between generation and simulation.

Choosing beta (grid expansion)

• beta = 0: uniform grid. Use for thin-layer (FD) simulations where concentration varies throughout. If beta = 0 causes numerical overflow, set a small non-zero value (e.g., 1e-6) instead.
• beta = 0.3–0.5: logarithmic expansion. Recommended for semi-infinite geometries (L, S, C, RDE). More grid points near the electrode surface.
• Too large a beta can cause numerical noise in slow-reaction zones. Start with 0.4.

Concentration profile resolution

For a detailed heatmap, set boxnum ≥ 100 and use CP<n>. The Gnuplot heatmap automatically scales x to dimensionless coordinates x/√(D_max·τ) and time to t/τ.

Multiple electron transfers

For a multi-step process where intermediates are detectable, define separate ETR lines:

1-e<->2|0.49|0.5|1|1e6;
2-e<->3|1.15|0.5|1|1e6.

Oxidation reactions

Use - before e to indicate oxidation (species loses electrons):

1-e<->2|0.0|0.5|1|0.01.

The sign of na is automatically derived from the +/- direction: the program multiplies the input na value by enum/Abs(enum). Therefore, always input na as a positive number.

Batch wrapper (run.bat)

@echo off
"C:\NETSIM\ecNetSimV10.x.exe" "%CD%\%~1"

Copy as ecnetsim.bat to a directory in PATH. Then:

cd C:\myproject
ecnetsim input.atn

15. Version History (selected)

End of Manual — ecNetSim_LTPS_NGS V10.7 & ecTrans V5.0