python docs update

docs/pycatima.md

@@ -0,0 +1,176 @@
+Usage
+=====
+
+Pojectile
+---------
+
+Projectile is defined by __pycatima.Projectile__ class. It is initialized using:
+
+**Projectile(A, Z, Q=Z, T=0)**
+
+where __A__ is mass in u units, __Z__ is proton number, __Q__ is charge state 
+and __T__ is energy in Mev/u units.
+
+```python
+import pycatima
+p = pycatima.Projectile(238.00032 ,92)  # 238U92+ at 0 Mev/u 
+p = pycatima.Projectile(238.00702 ,92,90,1000)  # 238U90+ at 1000 Mev/u 
+
+# following methods are defined:
+mass = p.A()  # get mass of the nucleus us u units
+z = p.Z()  # get proton number
+q = p.Q()  # get charge state
+energy = p.T()  # get energy
+p.T(1000)  # set energy
+```
+
+Material
+--------
+Material is defined by __pycatima.Material__ class. The recommended way of 
+initialization is usign the following init signature:
+
+**Material(elements, density, thickness, i_potential, mass)**
+  * elements - list of elements, where element is defined as list of [A, Z, STN]
+  A is atomic mass of the element, if 0 natural abundance atomic mass is taken, 
+  Z is the proton number of the element, STN is the stoichiometric if >=1.0 or
+  weight fraction if < 1.0
+  * density - optional, defaults to 0
+  * thickness - optional, if not defined 0
+  * i_potential - optional, if <=0 it will be calulated using Bragg rule from elemental ionization potentials
+  * mass - optional, if <=0 it will be calculated from elements masses and STN number.
+
+__Material__ class has following methods:
+
+  * **add_element(a, z, stn)** - adds another element to the material, see initialization comments for details about, a,z, stn 
+  * **ncomponents()** - returns number of elements in the material
+  * **density()** - returns density 
+  * **density(value)** - set density
+  * **thickness()** - get thickness in g/cm^2
+  * **thickness(value)** - set thickness in g/cm^2
+  * **thickness_cm(value)** - set thickness in cm
+  * **I()** - get mean ionization potential
+  * **I(value)** - set mean ionization potential
+
+### Default Materials
+The material with predefined density and atomic weights can be obtained for elemental targets and some compounds using:
+
+**pycatima.get_material(id)** 
+
+id is integer which identifies material, For elements use 1-99 for elemental targets and >200 for compounds. See available pre-defined compounds in __predefined material__ section in manual./
+
+
+### Example 
+
+```python
+import pycatima
+
+#H2O with natural atomic masses and Ipot=78eV
+h2o = pycatima.Material([[0,1,2],[0,8,1]],density=1.0, i_potential=78)
+h2o.thickness_cm(1.0) # 1cm of water
+# C target
+c_mat = pycatima.get_material(6)
+c_mat.thickness(0.1) # set to 0.1g/cm2 
+```  
+
+Layers
+------
+Layers are sequential layers of __Material__ which __Projectile__ passes.
+The __pycatima.Layers__ class is defined using following signature:
+**Layers()**
+This creates empty layers which needs to be filled by __Material__ class.
+
+__Layers__ clas has following methods:
+  * **add(material)** - add material to the layers, material must be __Material__ class
+  * **add_layers(other)** - add all material from __Layers__ class __other__
+  * **num()** - returns number of layers
+  * **__get_item__(i)** returns i-th Material class
+  * **__get(i)** returns i-th Material class
+  
+### Example
+
+```python
+import pycatima
+layers = pycatima.Layers()
+
+# define some materials
+graphite = pycatima.get_material(6)
+graphite.thickness(0.2)
+p10 = pycatima.get_material(pycatima.material.P10)
+p10.thickness_cm(2.0)
+air = pycatima.get_material(pycatima.material.Air)
+air.thickness_cm(2.0)
+
+# now add materials to layers
+layers.add(graphite)
+layers.add(air)
+graphite.thickness(0.1) # change thickness for next layer
+layers.add(graphite)
+layers.add(p10)
+```
+
+
+
+Calculation
+-----------
+Calculations are done using mainly via functions:
+
+* **calculate(Projectile, Material)**
+* **calculate_layers(Projectile, Layers)**
+
+The __calculate__ function returns __Result__ class and __calculate_layers__ returns __MultiResult_class__
+
+### Example
+```python
+import pycatima
+water = catima.get_material(catima.material.Water)
+water.thickness(1.0)
+p = catima.Projectile(1,1)
+p.T(1000)  # set projectile energy to 1000MeV/u
+
+res = catima.calculate(p,water) # now res contains results
+d = res.get_dict() # get results as dictionary
+```
+
+```python
+p = catima.Projectile(12,6)
+water = catima.get_material(catima.material.Water)
+water.thickness(10.0)
+graphite = catima.get_material(6)
+graphite.thickness(1.0)
+graphite.density(2.0)
+
+mat = catima.Layers()
+mat.add(water)
+mat.add(graphite)
+
+# now calculate results for projectile at 1000MeV/u
+res = catima.calculate_layers(p(1000),mat)
+```
+
+Results
+-------
+__Results__ class stores results for 1 layer of __Material__. It has following variables:
+
+  * Ein - Energy at entrance of the material in MeV/u
+  * Eloss - Energy loss in material in MeV
+  * Eout - Energy at the end of material in MeV/i
+  * dEdxi - Stopping power at entrance
+  * dEdxo - Stopping power at exit
+  * range - range in the material in g/cm^2
+  * sigma_E - Energy straggling in MeV/u
+  * sigma_a - Angular straggling in MeV/u
+  * sigma_r - range straggling in g/cm^2
+  * sigma_x - position straggling in cm
+  * sp - non-reaction probability
+  * tof - time of flight through the material
+
+__MultiResults__ class stores the results for multiple layers. It consists of following variables:
+ 
+  * total_result - __Result__ class with total results for projectile passing all layers.
+  * results - list of __Result__ classes, one for each layer in __Layers__
+
+
+
+Config
+------
+TODO

docs/pycatima.rst

@@ -1,17 +0,0 @@
-Usage
-=====
-
-Pojectile
----------
-
-Material
---------
-
-Layers
-------
-
-Calculation
------------
-
-Config
-------