User Manual
===========

	VirtualCV 1.0  

	(C) Copyright 1999, Andr Laounan

 
see also: 
  two formatted version are included: Manual.doc & Manual.htm

INTRODUCTION

In a hurry see QuickStart.

VirtualCV 1.0 is a program to perform Cyclic Voltametry electrochemical simulations. The simulation engine is a translation from Pascal to C++ of the David K. Gosser's engine found in CVSIM.
My first objective when I started writing VirtualCV was to design a user-friendly interface for an electrochemistry simulation program, and I put the emphasis on the graphical output. 
In VirtualCV, the simulation output is plotted on screen in what can be seen as "real time", although this is not absolutely true because the time scale isn't really taken into consideration. Nevertheless voltamogram (current, potential pairs, I = f(E)), concentration profiles at the electrode (Ci  = f(x) for all species) and excitation signal (potentiostat pilot E = f(t)) can be plotted in synchronism, giving the user the look and feel of a real experiment. This is a valuable aspect for teachers and students in the field of electrochemistry, because it gives an insight, on what is the diffusion layer, and what is happening inside it.
VirtualCV can simulate a lot of electrochemical mechanism (but not all), build as a combination of:
* an unlimited number of species
* an unlimited number of chemical reactions
* an unlimited number of independents redox couples
Many virtual (simulated) experiments can be displayed at the same time, along with many real voltamograms. A history list of virtual experiments is maintained during a session for an easy referencing, recalling and editing of mechanism parameters. Real voltamograms can be read from natives files created by Ecco Chemie, Tacussel/Radiometer, electrochemical software (EGG will come soon). These features allow an easy comparison between virtual and real tables voltamograms, and manual search and refinement of the electrochemical system parameters.
Limitations:
Related redox reactions (EE mechanisms) like: A ( A+  + e ( A++ + e, are limited to two mono-electronic steps (the same limitation apply to CVSIM program), see also special considerations below for entering data. Chemical reactions are limited to two reagents and two products. IR drop and capacitive current is not simulated (for now). Curve fitting and mechanism parameters adjustment is not ready yet.
File organization:
Input files formats: 
Mechanism definition files: *.CVN and *.MEC
Mechanisms can be read from ASCII files, either the VirtualCV native format *.CVN or the ESP *.MEC files. These text files can be written by any text editor or by the VirtualCV internal editor. File structure is simplistic and self-explanatory.
Virtual and real data files:
Data files created by Ecco Chemie (*.OCV), Tacussel/Radiometer (*.AA0), and EGG can be read, and their content displayed. Simulation from ESP (*.PRN) are also readable.
Output files formats:
Mechanism definition files: *.CVN and *.MEC
Mechanisms can be stored is an ASCII files, either the VirtualCV native format *.CVN or the ESP *.MEC files.
Virtual voltamogram data files: *.PRN ; *.OCV ;*.AA0
Simulated voltamograms can be stored as ASCII text files in 3 formats:
* Ecco Chemie *.OCV files: text file compatible with Ecco Chemie GPES software.
* Tacussel/Radiometer *.AA0 files: text file compatible with Tacussel software.
* ESP *.PRN files : text file format used by Carlo Nervi ESP simulation package 
* EGG formats are not currently supported but will be soon.

ELECTROCHEMICAL MECHANISM DEFINITION

The mechanism definition is build from species, redox reactions, and chemical reactions, there is a list box and an editor for each category.
Species
To begin adding, deleting or editing species click in the species list box (page "Model" in the bottom, right. panel), this bring to front an editor with his own toolbar. Each species is associated externally with an identifier (a name), and internally with an integer, in order of entry. Its identifier in subsequent operations within VirtualCV refers each species. For each species you should enter the corresponding initial normalized concentration, and the normalized diffusion coefficient which is taken as 1 by default. The normalization factor is 1E-5 by default for diffusion coefficients (but you can change it). The concentrations are normalized as millimolar (the default normalization factor is 1E-6). A special "Dummy" species is provided as a marker for no species (a non-existent species), and it can't be deleted. Other species can be added or inserted by clicking the add or insert button; and deleted by selecting them and clicking the kill button, as long they are not involved in a redox or chemical process (a check is made by the program). This check is made because deleting a species present in a reaction invalidate that reaction scheme. Changing the name, the concentration, or diffusion coefficient is done by selecting the species, changing its parameters in edit control, and applying (OK button click) or canceling changes.
Redox reactions
To enter a new redox reaction, open the redox reaction editor by clicking the redox reactions panel, then click the new or insert button, and then select Ox and Red species in corresponding list boxes. Enter the formal potential E', the heterogeneous rate constant and the transfer coefficient alpha, it editor boxes. Click the Apply button and the new reaction is entered is the mechanism.
To edit reaction parameters, follow the same procedure, just select the reaction to be edited in the reaction list box, instead of clicking the new button. To delete a reaction, select it, and then click the delete button. During editing you can click cancel button to end editing without saving last changes made in editor.
Chemical reactions
To enter a new chemical reactions, open the chemical reaction editor by clicking the chemical reactions panel, then click the new button, and then select at least a reagent, and a product species in corresponding list boxes. Enter the forward and reverse rates constants (Kf, Kb). Click the Apply button and the new reaction is entered is the mechanism.
To edit reaction parameters, follow the same procedure, but select the reaction to be edited in the reaction list box, instead of clicking new button. To delete a reaction, select it, and then click the kill button. While editing you can click the cancel button to end editing without saving last changes made in the editor.
As long as information is entered in editors, and validated by apply button a textual (human readable) summary is displayed in reactions list box.
Special considerations
You cannot specify less than one redox processes.
If a EE mechanism should be entered, i.e. (0/1-) (1-/2-) processes, it is ESSENTIAL to enter the two redox consecutively, for instance: 
	A2+ + e <=> A+
	A+  + e <=> A

There is no restriction in the case of independent redox processes.
The chemical reaction list box can be empty (No chemical reaction). Species number 0 (the "Dummy" species) means no species (i.e. "Dummy" is not an electroactive specie and doesn't participate furthermore to the overall mechanism). If "Dummy" is specified you must put it as last product or reactant. The homogeneous rate constant must be non-negative, they are in unity of s-1, for first order rate constant, and unity of 1/(mM*s) for second order rate constant.

EXPERIMENTAL PARAMETERS

Experimental parameters are the temperature, electrode area and pilot settings (the pilot panel is in the upper, left corner of the main window).
Temperature must be given in Kelvin
Electrode area: is given in cm2 (see general page in right, bottom panel). The current is proportional to electrode area (true current, not current density). 
Scan Rate: is given in V.s-1.
Four distinct potential values can be specified for scan definition.
* Initial Potential (IP): is given in V
* Switch1 Potential (ES1): is given in V.
* Switch2 Potential (ES2): is given in V.
* Final Potential (FP): given in V.

Number of half-cycles must also be specified: valid values are: one, two, or three.
* For one half-cycle: potential scans start at IP, and stop at ES1.
* For two half-cycles: potential scan start at IP goes to ES1, at ES1 scan direction is reversed and the scan continue until ES2 is reached. ES2 must be found during reverse scan, or result isn't what is expected.
* For three half-cycles: potential scan start at IP goes to ES1, at ES1 scan direction is reversed and the scan continue until ES2 is reached, where potential scan direction is reversed again. Scan is stopped when final potential is reached. Constraints exist on potential for the scan to be correct. VirtualCV performs no check.
During scan, the potential versus time display is optional. See the small "T" check box, (here "T" stand for "Track") displayed in upper, left corner of the pilot window (E = f(t)).
Uncompensated resistance. and double layer capacity effects are not supported yet (given values are ignored). 

EDITING MECHANISM

Editing is described in previous section about input mechanism. To reload editor with a previously played virtual experiment, just click the corresponding line in the history list box. If you don't like reloading on simple selection in the history list box, you can check the "reload on double click" radio button in the preference page.

RUNNIG AN EXPERIMENT

To run an experiment, click the start button in the pilot panel. During scan the hold button can be clicked, this hold the potential constant until the button is clicked again (the button give feed back), the time is still running when "holding" the potential, real time effect can be seen in concentration graph and voltamogram graph. The Freeze button completely suspends the simulation, a second click on the Freeze button resume simulation. The experiment can be aborted by a click on the start button while simulation is running. The simulation is aborted and no results are stored. When experiment reach a normal end, the simulation result is saved in the history list (a default name for the virtual experiment is build by the program), where it stays until the program is exited. Entry in history list (and associated virtual experiments) can be saved to disk, plotted to screen, hidden from plot, recalled for edition, and deleted from memory. VirtualCV doesn't create duplicates entry in history, when the same experiment is run many times. Optionally, saving to history can be controlled manually (see preferences/options page). 

SAVING, LOADING EXPERIMENTS (REAL AND VIRTUAL)

The experiment selected in history list can be save to disk file via a button in main toolbar and a standard dialog (with a selection for file type). Saved experiments can be reloaded via a main toolbar button; the program maintains a list of virtual and real experiments read from disk files. Voltamograms can be displayed, hidden, smoothed (Savitsky-Golay algorithm), searched for peaks and finally deleted from memory.

VOLTAMOGRAM DISPLAY PANEL

Voltamograms are plotted in a resizable panel with it's own toolbar, and a powerful editor is provided for fine-tuning of plots (first button on toolbar). Plots can be printed (with preview) and exported via the clipboard, or files (bitmaps and window metafiles supported). Graphs produced are nearly ready for publication. Mouse coordinates are displayed in user units, and curve identification is displayed as hint message. A peak search facility is provided via a button in the toolbar. A spin control is provided to define the number of points used when smoothing experimental curves. The smoothed curve is recomputed when the spin control value is changed. Next to the spin button is small button to allow zoom out operation (not easy with the mouse). Zoom in, is allowed via the mouse: draw a rectangle holding down the left mouse button, from left-top to right-bottom over the region you want to magnify. To restore normal display, drawn a rectangle, but from right-bottom corner to the left-top one. Dragging with the right mouse button does panning.
Optionally, the voltamogram is plotted during the scan (computation here); this gives the feeling of performing a real experiment. As the plotting process is time consuming (especially when many curves are already on display) it can be disabled, see the "T" check box in the toolbar.

Special series:
 There is 4 special series, with predefined usage:
 dI/dE is the derivative computed in last operation.
 SimPeaks is used to show peaks in currently selected virtual voltamogram.
 ExpPeaks is used to show peaks in currently selected real voltamogram.
 ExpSmooth is used to draw a smoothed experimental voltamogram if needed.
The other series are for virtual or experimental voltamogram plots.
NB: peaks representation is limited to the selected series to avoid excessive decoration and confusion.
 

The graph editor: Almost any detail of the graph can be set via this tool. I will not describe it in detail, spend a few time playing with it. Changes made are reflected immediately, so it easy to learn. The left panel list box presents the curves (called series). Some curves are predefined like dI/dE used to store derivatives, and may be empty. To display a curve check it in the list box, to hide a curve uncheck it. Many commands are applied to the selected series (like changing display style, color...). Hints provide some help, the graph editor isn't a finished component and there is no more help (as I intend to upload the component to the net, I'll write some doc, if I find the time).
Known bug: Zooming and panning is provided by TeeChart library, unfortunately the library doesn't seems to be reliable when a zoom is done on curve like CV voltamograms were there is two (or more) Y values for the same X value. In such case the X-axis can't be sorted and the library seems to be confused sometimes, causing the plot to disappear.

QUICK START

After successful installation you're ready to run your first simulation: just click the start button in the upper left panel, and look at the result. 
If something doesn't work as expected see known bugs.
Then you can try editing mechanism in the right bottom panels (page Model). For a more spectacular show, check the small "T" check box inside the three left panels (on toolbars), click start button, and view the running virtual experiment.


NOTES

About the manual: 
Since my native language is French, please be indulgent, I will be very glad to include any improvement and correction to this document.
For basics about electrochemistry, see for instance: 
* A.J.Bard, L.R.Faulkner, Electrochemical Methods. Fundamentals and Applications, Wiley, New York, 1980. 
* Z.Galus, Fundamentals of Electrochemical Analysis. 2nd (revised) edition., Ellis Horwood and Polish Scientific Publishers, New York and Warsaw, 1994. 
* D.Britz, Digital Simulations in Electrochemistry, Second, revised and extended edition, Springer-Verlag, Berlin, 1988. 
* David K. Gosser, Cyclic Voltammetry Simulation and analysis of Reactions Mechanisms, VCH Publishers, New York, 1993. 

Author, Bugs and Suggestions: 
-----------------------------
Any suggestions, encouragement, post cards, beer, money, and of course bugs reports about VirtualCV are welcome.
e-mail: andre.laouenan@univ-brest.fr

Credits: 
The simulation engine is adapted from the work of David K. Gosser. 

The Rx Library for C++ Builder and Delphi is used in this software. To get more information on RX Library please, take a look at the RX Library home page that can be found on the Internet at http://rx.demo.ru/.

The Toolbar97 component by Jordan Russell is used in VirtualCV.
To get more information see: Jordan Russell
e-mail: jordanr7@aol.com
Home page: http://members.aol.com/jordanr7

Hardware requirements: 
PC IBM or compatible 486, Pentium CPU, color VGA graphics, 1024*768 (or better) is recommended.

Known Bugs: 

This software has been developed on a French Windows98 system, using a French C++ Builder 3.0 development tool. It's the first time I upload one of my software, and I'm not very cleaver about the art of writing international application software. I hope that this software can run on an English Windows98 system, if it's not the case, please let me know (even if you are very busy, or think you've downloaded: Yet Another Useless Software), before throwing VirtualCV to the dustbin, try to change your decimal separator from comma to dot or vice versa.
Although, in certain configurations of zoom, tool bars can be lost (remain invisible), in most configurations it must be Ok.
VirtualCV interface isn't fool proof, it can certainly be confused (defeated) by unusual practices let me know the weakness you could experience.
VirtualCV hasn't been tested for memory leaks (because I doesn't have a good tool for that), so I believe that there are some leaks, if you know a good (free, or at lest inexpensive) tool for avoiding memory leaks, let me know. In a dream I saw a garbage collector for C++, but it's still only available for Java.  (I had a dream about it, but Sony (i.e. Borland,  Inprise) doesn't do it). Bug report is welcome, please send me an e-mail.


Software requirements: 
  VirtualCV runs under Windows98. It has NOT been tested but it should be happy with Windows95 and Windows NT.
  the system file: COMCTL32.DLL version must be 4.70 or later. The install programm will install COMCTL32.DLL
  in your system if your version is less than 4.70.

Installation :
An installation program is provided. Unzip the archive content to a temporary folder, and start the setup.exe program, then follow instruction on screen. To uninstall VirtualCV follow the standard Windows uninstall procedure, in the configuration panel, via the add/suppress program icon.

License:
VirtualCV is copyrighted by Andr Laounan, and is distributed under the terms of the GNU general public license (a copy is enclosed in archive).

ESP :
ESP is the Electrochemical Simulation Package written by Carlo Nervi. It's a more powerful simulator than VirtualCV, but it's a dos program. Mechanism definition files *.MEC and *.PRN files can be read by VirtualCV.  

To Be Done:
Extend supported experimental data format (EGG is not currently supported).
Extend simulation to other voltametric methods.
Allow automatic curve fitting.

Files Content :
--------------
  VtlCV10.ZIP contains the following files:

License.txt	the GNU license.
Readme.txt	general information's about VirtualCV.
Manual.txt	this file: Few help about VirtualCV 1.0: 
how to install, getting started, how to use it.
Manual.doc	same content as Manual.txt but formatted for MS Word.
Manual.htm	same content as Manual.txt but in HTML format.
Setup.exe	the installations program, run Setup.exe to install VirtualCV 1.0 on your computer.

