// $Id: calcrxc.hoc,v 1.7 2014/08/17 16:27:20 ted Exp $
/* Calculates the transfer resistances between 
extracellular stimulating|recording electrode(s) and a 
model neuron.  Relies on the principle of reciprocity, 
which assumes that the intervening bath and tissue can 
be treated as linear.  Suppose a stimulus current of 
amplitude Is, applied to a particular configuration of 
extracellular electrode(s), produces a potential Vext(x,y,z) 
at location (x,y,z).  Then the transfer resistance between 
the electrode(s) and (x,y,z) is 
  rx(x,y,z) = Vext(x,y,z)/Is
According to the principle of reciprocity, a transmembrane 
current Im(x,y,z) generated by membrane at (x,y,z) will 
produce a potential Vel that can be recorded at the 
extracellular electrode(s) and is given by
  Vel = rx(x,y,z) Im(x,y,z)


-----------------------------------------
How to simulate extracellular stimulation
-----------------------------------------

Insert the extracellular and xtra mechanisms in all sections that are 
subject to the extracellular field.
Compute the transfer resistance rx for every section that contains 
xtra, as illustrated below.
Construct a stimulus waveform template and copy it to a Vector.  
For each internal node along the axon, use this Vector to drive 
is_xtra(x).  The xtra mechanism uses the rx values to convert the 
stimulus current waveform into the proper amplitude and sign of the 
local extracellular field.

If rho, b, or c is changed, new_elec() must be invoked 
to make the changes take effect.


-----------------------------------------
Monopolar electrode in an infinite medium
-----------------------------------------

A conductive sphere of radius r0 is suspended in an infinite 
volume of solution that has resistivity rho [ohm cm].  Ignoring 
electrochemical effects at the electrode|solution interface, 
what is the resistance between the surface of the sphere and 
an infinitely distant ground electrode?

The surface area of a sphere with radius r is 4 PI r^2.
The resistance of a shell with thickness dr is 
  rho dr / 4 PI r^2
and the resistance is therefore
    inf
  INTEGRAL rho dr / 4 PI r^2
    r0
                     inf
   = - rho / 4 PI r |     = rho / 4 PI r0
                     r0
So to a first approximation, a monopolar stimulating electrode 
that delivers current I produces a field in which potential V 
is given by 
  V = I rho / 4 PI r
where r is the distance from the center of the electrode.

The principle of superposition may be applied to deal with an 
arbitrary number of monopolar electrodes, or even surface 
electrodes with different shapes and areas, which are located 
at arbitrary positions, and deliver arbitrary stimulus currents.
However, there are some noteworthy special cases.


---------------------------------------------
Special case:  bipolar stimulation of an axon
---------------------------------------------

Imagine a pair of stimulating electrodes that lie along 
a line parallel to an axon, like so:

=====================   ---
                         c
       o     o          ---
       |  b  |
       1     2

where b is the separation between the electrodes 
and c is the perpendicular distance from them to the axon.

For the sake of this example, assume that the electrodes 
straddle the midpoint of the axon.

The extracellular potential at location x produced by electrode 
1 is
  V1 = I rho / 4 PI r1
where r1 is the distance from electrode 1 to x.  This distance is
  r1 = sqrt( ((x-0.5)*L) + 0.5*b)^2 + c^2 )

Likewise the potential at x produced by electrode 2 is
  V2 = -I rho / 4 PI r2
where r2 is the distance from electrode 2 to x, i.e.
  r2 = sqrt( ((x-0.5)*L) - 0.5*b)^2 + c^2 )

The net extracellular potential at x is V1 + V2, i.e.
  Vnet = (I rho / 4 PI)*((1/r1) - (1/r2))
so the transfer resistance that converts the stimulus current I to 
an extracellular potential Vnet is simply
  rx = (rho / 4 PI)*((1/r1) - (1/r2))


--------------------------------------------------------
Special case:  uniform field between two parallel plates
--------------------------------------------------------

A uniform field has the same intensity and orientation at all 
points in space, and the extracellular potential at any point
is a linear function of displacement in the direction of the 
orientation of the field.

If an entire neuron lies in such a field, then without loss of 
generality we may assert that the extracellular potential is 0 
for all points that lie on some plane that is perpendicular to 
the field.  For this "zero potential surface" it is convenient 
to choose the plane that passes through a particular location 
in the cell, such as the 0 end of the soma.

*/

// set up the transfer resistances

// what is the approximate resistivity of tissue anyway?
rho = 35.4  // ohm cm, squid axon cytoplasm
	    // for squid axon, change this to seawater's value
	    // for mammalian cells, change to brain tissue or Ringer's value

/*
b = 400  // um between electrodes
c = 100  // um between electrodes and axon

proc setrx() {
  forall {
    if (ismembrane("xtra")) {
// avoid nodes at 0 and 1 ends, so as not to override values at internal nodes
      for (x,0) {
        r1 = sqrt( ((x-0.5)*L + 0.5*b)^2 + c^2 )
        r2 = sqrt( ((x-0.5)*L - 0.5*b)^2 + c^2 )
        // 0.01 converts rho's cm to um and ohm to megohm
        axon.rx_xtra(x) = (rho / 4 / PI)*((1/r1) - (1/r2))*0.01
// print r1, r2
      }
    }
  }
}
*/

// assume monopolar stimulation and recording
// electrode coordinates:
// for this test, default location is 50 microns horizontal from the cell's 0,0,0
XE = soma.x_xtra  // um
YE = soma.y_xtra
ZE = soma.z_xtra

proc setrx() {  // now expects xyc coords as arguments
  forall {
    if (ismembrane("xtra")) {
// avoid nodes at 0 and 1 ends, so as not to override values at internal nodes
      for (x,0) {
        r = sqrt((x_xtra(x) - xe)^2 + (y_xtra(x) - ye)^2 + (z_xtra(x) - ze)^2)
//        r = sqrt((x_xtra(x) - $1)^2 + (y_xtra(x) - $2)^2 + (z_xtra(x) - $3)^2)
        // 0.01 converts rho's cm to um and ohm to megohm
        // if electrode is exactly at a node, r will be 0
        // this would be meaningless since the location would be inside the cell
        // so force r to be at least as big as local radius
        if (r==0) r = diam(x)/2
        rx_xtra(x) = (rho / 4 / PI)*(1/r)*0.01
      }
    }
  }
}

create sElec  // bogus section to show extracell stim/rec electrode location
proc put_sElec() {
	sElec {
		// make it 1 um long
		pt3dclear()
		pt3dadd($1-0.5, $2, $3, 1)
		pt3dadd($1+0.5, $2, $3, 1)
	}
}
put_sElec(XE, YE, ZE)

objref gElec  // will be a Shape that shows extracellular electrode location
gElec = new Shape(0)  // create it but don't map it to the screen yet
gElec.view(-245.413, -250, 520.827, 520, 629, 104, 201.6, 201.28)
objref pElec  // bogus PointProcess just to show stim location
sElec pElec = new PointProcessMark(0.5) // middle of sElec
gElec.point_mark(pElec, 2) // make it red

proc setelec() {
	xe = $1
	ye = $2
	ze = $3
	setrx(xe, ye, ze)
	put_sElec(xe, ye, ze)
}

// setrx(50, 0, 0)  // put stim electrode at (x, y, z)

setelec(XE, YE, ZE)  // put stim electrode at (x, y, z)

// print "Use setelec(x, y, z) to change location of extracellular recording electrode"

xpanel("Extracellular Electrode Location", 0)
  xlabel("xyz coords in um")
  xvalue("x", "XE", 1, "setelec(XE,YE,ZE)", 0, 1)
  xvalue("y", "YE", 1, "setelec(XE,YE,ZE)", 0, 1)
  xvalue("z", "ZE", 1, "setelec(XE,YE,ZE)", 0, 1)
xpanel(855,204)