installable package

Author: Kiran Vaddi

Readme.md

@@ -4,7 +4,7 @@ This is a python wrapper for [MECSim](http://www.garethkennedy.net/MECSim.html)
 It works completely in python in a Linux environment. I wrote this while working on [GPCV](https://github.com/kiranvad/gpcv) related work. 
 
 If you use this software in your work please cite the original MECSim software along with this repository:
-```
+```bibtex
 @misc{pymecsim,
     author       = {Kiran Vaddi},
     title        = {{pyMECSim: A Python wrapper for MECSim}},
@@ -15,17 +15,17 @@ If you use this software in your work please cite the original MECSim software a
     url          = {https://github.com/kiranvad/pyMECSim}
     }
 ```
-
-This repository is arranged as follows:
-1. src  : Contains the original MECSim software distributed under the same license as MECSim
-2. notebooks :  An example usage of pyMECSim is shown.
-3. mechanisms : Folder where you can host a original mechanism as an input file 
+To install as a package, run 
+```bash
+pip install git+https://github.com/kiranvad/pyMECSim#egg=pyMECSIM.` 
+```
+Dependencies will be checked and installed from the setup.py file.
 
 A sample usage is as follows:
 
 Import `pymecsim` using the following: 
 ```python
-from src.pymecsim import MECSIM, pysed, plotcv
+from pymecsim import MECSIM, pysed
 ```
 We can perform a simulation on a one electron transfer mechanism and visualize the effect of changing the formal potential using the following code:
 
@@ -42,26 +42,32 @@ dirname = os.getcwd()
 for i,e0 in enumerate(E0):
     outfile = dirname + '/outfile.sk'
     pysed('$E0', str(e0), configfile, outfile)
-    out = MECSIM(outfile)
-    ax = plotcv(out['current'],out['voltage'], ax = ax)
+    model = MECSIM(outfile)
+    ax = model.plot(ax = ax)
     ax.set_label("E0 = "+str(e0))
 plt.legend([r'$E_0=0.5$',r'$E_0=0.1$',r'$E_0=1e-2$'],loc='lower right')
 #plt.savefig('cvexample.png',dpi=500,bbox_inches='tight')
 plt.show()
 ```
 
 This will plot the following:
-<img src="notebooks/cvexample.png" width="600">
+<img src="notebooks/cvexample.png" width="400">
 
 
 Naturally, you would want to be able to run simulations for different mechanisms and confgurations. You can do that by just defining a mechanism that MECSim can model(see examples for some possible reaction mechanisms [here](http://www.garethkennedy.net/MECSimScripts.html)).
 
 Once you have the mechanism file in say `/path/to/folder/mechanism.sk` format, turn it in as an input to pyMECSim using the following:
 ```python
-out = MECSIM('/path/to/folder/mechanism.sk')
-plotcv(out['current'],out['voltage'])
+model = MECSIM('/path/to/folder/mechanism.sk')
+model.plot()
+plt.show()
 ```
 
+One can also get concentration profiles by first indicating `MECSIM` to return concentration profiles in the configuration file by setting `1		! show debug output files as well as MECSimOutput.txt (1=yes; 0=no)`. `pymecsim` will then be able to return concentration profiles as numpy arrays. see `notebooks/Cyclic Voltammetry Simulation Example for Single Electron Transfer Mechanism.ipynb` for an example use case.
+
+
+## Notes
+Please free to contribute to this repository both interms of code and documetation or simple example use cases in jupyter notebook. Submit a pull request and I would be happy to integrate into this repository.
 
 
 

__init__.py

@@ -15,7 +15,7 @@
 10.0		! Dstar_min
 0.005e0	! max voltage step
 25.6e0	! time resolution experimentally to correct vscan/f (us)
-0		! show debug output files as well as MECSimOutput.txt (1=yes; 0=no)
+1		! show debug output files as well as MECSimOutput.txt (1=yes; 0=no)
 0		! use advanced voltage ramp (0 = E_start=E_end, 1 = use advanced ramp below, 2=From file "EInput.txt")
 2     	! number of E_rev lines for advanced ramp (if enter 0 then first E_rev value is the final time
 0.0		! E_start (V)

mechanisms/cvexamples.sk

@@ -0,0 +1,116 @@
+
+ *****************************************************
+                 MECSim - GK 7/08/2016
+ *****************************************************
+
+
+
+ General parameters:
+      Temperature =   298.2000
+  Uncompensated R =        0.0
+
+ Voltage ramp (V):
+      E_start =   0.5000
+        E_rev =  -0.5000
+        E_end =   0.5000
+       Cycles =    1
+  Total range =   2.0000
+
+ Scan rate (V/s) =   1.00000000E+01
+  Final time (s) =   2.00000000E-01
+
+Found   1 AC signal(s). Max frequency =   0.0000 Hz
+          0.0000 mV at   180.0000 Hz
+
+ No capacitor requested
+
+
+ Found a total of   2 species
+
+ No pre-equilibriation; use entered concentrations
+
+ Summary of solution reactions:
+     Charge transfer =  1
+      1st Order Chem =  0
+      2nd Order Chem =  0
+ Summary of surface confined reactions:
+     Charge transfer =  0
+      1st Order Chem =  0
+      2nd Order Chem =  0
+
+ Charge transfer reaction(s):
+     A +  1e = B       ; E0 =   0.250 , ks =   1.0000E+04 cm/s , alpha =   0.50
+                       ; K_eqm =   1.6794E+04
+
+ Electrode geometry:
+   Planar with area =   1.00000000E+00 cm^2
+
+ Technical details of simulation
+   Using Butler-Volmer Theory
+   Points in time = 2^14 =    16384
+   delt =   1.2207E-05 and delE =   1.2207E-04
+    Exponential spatial grid with  57 points and delx(0) =   3.4939E-06
+   x =   1.7033E-06  5.3763E-06  9.4355E-06  1.3922E-05 |   9.4112E-03
+
+ Solution phase:
+ Initial scaled concentrations and diffusion coeff (cm2/s)
+ [A] =   1.00000000E-06 ; D =   1.00000000E-05
+           (1.00000000)
+ [B] =   0.00000000E+00 ; D =   1.00000000E-05
+           (0.00000000)
+ Concentrations scaled by   1.00000000E-06 mol/cm3
+                            1.00000000E+00 mM
+
+
+ ************** Starting Time Loop ******************
+
+ Done  10%; t,Eapp,i =   2.00E-02  3.00E-01 -7.11E-04,  C_err= -2.87E-12
+    0.8752    0.1248    0.0000    0.0000    0.0000    0.0000
+ Done  20%; t,Eapp,i =   4.00E-02  1.00E-01 -1.47E-03,  C_err= -1.78E-12
+    0.0029    0.9971    0.0000    0.0000    0.0000    0.0000
+ Done  30%; t,Eapp,i =   6.00E-02 -1.00E-01 -9.27E-04,  C_err= -1.26E-12
+    0.0000    1.0000    0.0000    0.0000    0.0000    0.0000
+ Done  40%; t,Eapp,i =   8.00E-02 -3.00E-01 -7.36E-04,  C_err= -1.42E-12
+    0.0000    1.0000    0.0000    0.0000    0.0000    0.0000
+ Done  50%; t,Eapp,i =   1.00E-01 -5.00E-01 -6.29E-04,  C_err= -1.62E-12
+    0.0000    1.0000    0.0000    0.0000    0.0000    0.0000
+ Done  60%; t,Eapp,i =   1.20E-01 -3.00E-01 -5.59E-04,  C_err= -1.83E-12
+    0.0000    1.0000    0.0000    0.0000    0.0000    0.0000
+ Done  70%; t,Eapp,i =   1.40E-01 -1.00E-01 -5.08E-04,  C_err= -2.06E-12
+    0.0000    1.0000    0.0000    0.0000    0.0000    0.0000
+ Done  80%; t,Eapp,i =   1.60E-01  1.00E-01 -4.51E-04,  C_err= -3.06E-12
+    0.0029    0.9971    0.0000    0.0000    0.0000    0.0000
+ Done  90%; t,Eapp,i =   1.80E-01  3.00E-01  2.10E-03,  C_err= -6.10E-13
+    0.8747    0.1253    0.0000    0.0000    0.0000    0.0000
+ Done 100%; t,Eapp,i =   2.00E-01  5.00E-01  6.93E-04,  C_err= -2.34E-12
+    0.9999    0.0001    0.0000    0.0000    0.0000    0.0000
+
+ Concentration min/max values:
+    0.0000    0.0000    0.0000    0.0000    0.0000    0.0000
+    1.0000    1.0000    0.0000    0.0000    0.0000    0.0000
+
+ ****************************************************
+
+ Current minimum =  -2.68622429E-03 and maximum =   2.24577576E-03
+ Voltage minimum =   2.21557617E-01 and maximum =   2.78686523E-01
+
+   Average number of iterations at electrode surface =    1.000
+ Average number of iterations for chemical reactions =    1.000
+ Average ODE calculations for iterating surface conf =    0.000
+  Average ODE calculations for bounding surface conf =    0.000
+
+ Final scaled concentrations on spatial grid
+ [A] =   9.99940454E-01  9.98716251E-01  9.96076410E-01 |   9.99998347E-01
+ [B] =   5.95460837E-05  1.28374882E-03  3.92359046E-03 |   1.65337954E-06
+
+ Error in concentration sum (=0 if D_A = D_B etc)
+        -2.34245956E-12 -2.34312569E-12 -2.34601227E-12 |   6.50146603E-13
+
+
+ Output file written to MECSimOutput_Pot.txt
+
+
+ Additional files written to
+   EC_Model.tvc - time, Eapp and concentrations for all time steps (first number is #species)
+   EC_Model.fin - final concentrations against distance from electrode
+

notebooks/.ipynb_checkpoints/Cyclic Voltammetry Simulation Example for Single Electron Transfer Mechanism-checkpoint.ipynb

@@ -15,7 +15,7 @@
 10.0		! Dstar_min
 0.005e0	! max voltage step
 25.6e0	! time resolution experimentally to correct vscan/f (us)
-0		! show debug output files as well as MECSimOutput.txt (1=yes; 0=no)
+1		! show debug output files as well as MECSimOutput.txt (1=yes; 0=no)
 0		! use advanced voltage ramp (0 = E_start=E_end, 1 = use advanced ramp below, 2=From file "EInput.txt")
 2     	! number of E_rev lines for advanced ramp (if enter 0 then first E_rev value is the final time
 0.0		! E_start (V)

notebooks/Cyclic Voltammetry Simulation Example for Single Electron Transfer Mechanism.ipynb

@@ -0,0 +1,15 @@
+from setuptools import setup,find_packages
+import sys, os
+
+setup(name="pymecsim",
+      description="Python Cyclic Voltammetry Simulator",
+      version='1.0',
+      author='Kiran Vaddi',
+      author_email='[email protected]',
+      license='MIT',
+      python_requires='>=3.6',
+      install_requires=['numpy','scipy', 'pandas'],
+      extras_require = {},
+      packages=find_packages(),
+      long_description=open('Readme.md').read()
+)

notebooks/log.txt

@@ -1 +1,3 @@
-from .pymecsim import *
+#from .pymecsim import *
+from .utils import pysed
+from .core import MECSIM