lptolik · davidcsterratt · Apr 3, 2014 · Jun 19, 2014 · Jun 19, 2014 · Jun 19, 2014
diff --git a/.gitignore b/.gitignore
@@ -5,4 +5,8 @@
 *.pyc
 *.pdf
 *.class
-
+*.tokens
+python/build
+python/dist
+python/SpatialKappa.egg-info
+python/SpatialKappa/share
diff --git a/Makefile b/Makefile
@@ -5,9 +5,16 @@
 # OR sudo apt-get install antlr3
 
 # N.B.: The CLASSPATH has to have both parts and has to be aboslute
-CLASSPATH=$(realpath .)/src/lib/antlr-3.2.jar:$(HOME)/.ant/lib/ant-antlr3.jar 
+CLASSPATH=$(realpath .)/src/lib/antlr-3.2.jar:$(realpath .)/ant-antlr3.jar 
+
+SKJAR_FILE = SpatialKappa-v2.1.5.jar
+ANTLRJAR_FILE = ant-antlr-3.2.jar
+PYTHON_SHARE_DIR = python/SpatialKappa/share/SpatialKappa
 
 all: 
 	cd build && ant
 	cd build && CLASSPATH=$(CLASSPATH) ant compile-all
-	cd build && ant -f buildSpatialKappa.xml
+	cd build && ant -f buildSpatialKappa.xml
+	mkdir -p $(PYTHON_SHARE_DIR)
+	cp $(SKJAR_FILE) $(PYTHON_SHARE_DIR)
+	cp $(ANTLRJAR_FILE) $(PYTHON_SHARE_DIR)
diff --git a/README.md b/README.md
@@ -4,22 +4,48 @@ SpatialKappa
 <p style="text-align: center;">14 September 2012</p>
 
 <p style="text-align: center;">Copyright &copy; 2012 DemonSoft.org
-&lt;<a href="http://www.demonsoft.org/">http://www.demonsoft.org/</a>&gt;</p>
+&lt;<a
+href="http://www.demonsoft.org/">http://www.demonsoft.org/</a>&gt;<br/>
+Copyright &copy; 2014-2019 David C Sterratt <david.c.sterratt@ed.ac.uk>
+</p>
 
-<h4>INTRODUCTION</h4>
+INTRODUCTION
+------------
 
-<p>This project contains an implementation of a syntactic extension
-of Kappa to allow expression of location and transport in models. A user manual is available [here][manual-link].</p>
+This project contains an implementation of a syntactic extension
+of Kappa to allow expression of location and transport in models. A user manual is available [here][manual-link].
 
-Feel free to add bug reports or feature requests [here][bug-link].</p>
+Feel free to add bug reports or feature requests [here][bug-link].
 
-<h4>LICENSE</h4>
+INSTALLATION
+------------
 
-<p>This project is licenced under the GNU Lesser General Public
-Licence Version 3 (LGPLv3), included as &lt;<a href="LICENSE.html">LICENSE.html</a>&gt;.
+Either 
+
+1. Run the standalone jar file (SpatialKappa-v2.1.3.jar)
+2. Install the python interface using pip:
+```pip install SpatialKappa``` and then test using ```python -m unittest SpatialKappa.tests```. Within python ```help(SpatialKappa)``` gives the list of model-building and control functions.
+
+
+COMPILATION
+-----------
+
+To make the `SpatialKappa.jar` file either:
+
+1. Import this code as an Ecclipse project; or
+2. Install ant (`sudo apt install ant openjdk-7-jdk` on Debian/Ubuntu) and run `make all`
+
+To install the python interface, cd into the python directory, and
+follow the instructions in [python/INSTALL.md](python/INSTALL.md)
+
+LICENSE
+-------
+
+This project is licenced under the GNU Lesser General Public
+Licence Version 3 (LGPLv3), included as [LICENSE.html](LICENSE.html).
 
 Included third party libraries are released under their respective
-licences, listed below:</p>
+licences, listed below:
 
 <table style="border: groove;">
 	<tr>
@@ -76,27 +102,28 @@ licences, listed below:</p>
 </table>
 
 
-<h4>ACKNOWLEDGEMENTS</h4>
+ACKNOWLEDGEMENTS
+----------------
 
-The development of Spatial Kappa was funded in part by <a href="http://www.csbe.ed.ac.uk/">SynthSys</a>. SynthSys is a Centre for 
-Integrative Systems Biology (CISB) funded by BBSRC and EPSRC, reference BB/D019621/1.
+The development of Spatial Kappa was funded in part by <a href="http://www.csbe.ed.ac.uk/">SynthSys</a>. SynthSys is a Centre for Integrative Systems Biology (CISB) funded by BBSRC and EPSRC, reference BB/D019621/1.
 
+<img width=200px align="left" alt="EU flag" src="docs/figs/flag_yellow_low.jpg"/>
 
-<h4>DISCLAIMER</h4>
+This open source software code was developed with funding from the
+European Union Seventh Framework Programme (FP7/2007-2013) under grant
+agreement nos. 241498 (EUROSPIN project), 242167 (SynSys-project) and
+604102 (Human Brain Project), and in the Human Brain Project, funded
+from the European Union’s Horizon 2020 Framework Programme for
+Research and Innovation under Specific Grant Agreements No. 720270 and
+No. 785907 (Human Brain Project SGA1 and SGA2).
 
-<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
-CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
-BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
-USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
-THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
 
+DISCLAIMER
+----------	
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 [bug-link]: https://github.com/lptolik/SpatialKappa/issues
 [manual-link]: https://github.com/lptolik/SpatialKappa/raw/master/docs/manual/SpatialKappaManual-v2.1.0.pdf
-
+[1]: python/INSTALL.md
diff --git a/SpatialKappa-v2.1.1.jar → SpatialKappa-v2.1.5.jar b/SpatialKappa-v2.1.1.jar → SpatialKappa-v2.1.5.jar
diff --git a/ant-antlr3.jar b/ant-antlr3.jar
diff --git a/build/buildSpatialKappa.xml b/build/buildSpatialKappa.xml
@@ -3,7 +3,7 @@
     <!--this file was created by Eclipse Runnable JAR Export Wizard (then tweaked) -->
     <!--ANT 1.7 is required                                        -->
     <target name="create_run_jar">
-        <property name="VERSION" value="v2.1.1"/> <!-- Remember to update this -->
+        <property name="VERSION" value="v2.1.5"/> <!-- Remember to update this -->
 
     	<property name="JAR_FILENAME" value="SpatialKappa-${VERSION}.jar"/>
 

diff --git a/docs/figs/flag_yellow_low.jpg b/docs/figs/flag_yellow_low.jpg
diff --git a/docs/manual/KaSim_manual_v3.5.pdf b/docs/manual/KaSim_manual_v3.5.pdf
diff --git a/docs/manual/README.md b/docs/manual/README.md
@@ -0,0 +1,10 @@
+# SpatialKappa manuals
+
+Documents
+
+* [The main SpatialKappa manual](SpatialKappaManual-v2.1.0.pdf)
+
+* [Manual for tranalating SpatialKappa files into files compatible with v2.01 of KaSim](SpatialKappaTranslatorManual-v2.0.1.pdf)
+
+* [KaSim v3.5 manual, for fuller description of Kappa Language](KaSim_manual_v3.5.pdf) -
+  Note that SpatialKappa does not implement the full spec.
diff --git a/python/INSTALL b/python/INSTALL
diff --git a/python/INSTALL.md b/python/INSTALL.md
@@ -0,0 +1,41 @@
+Installing the Python interface to SpatialKappa
+===============================================
+
+0. Build the SpatialKappa jar as described in [../README.md][1]
+
+1. Either:
+
+   a. Install py4j using `pip`:
+
+        sudo apt-get install python-pip 
+        sudo pip install py4j --upgrade
+
+      To install in a non-standard location, use the `-t` flag, e.g.:
+
+        pip install py4j --upgrade -t ${HOME}/lib/python2.7/site-packages/
+
+   b. Install py4j with python 2.7 from source:
+
+        git clone https://github.com/davidcsterratt/py4j
+        cd py4j
+        cd py4j-java
+        ant jar
+        cd ../py4j/py4j-python
+        sudo python2.7 setup.py install
+
+
+2. Install SpatialKappa python files
+
+        sudo python2.7 setup.py install
+
+    An alternative prefix can be specified like this:
+
+        python2.7 setup.py install --prefix=${HOME}
+
+3. Run the tests:
+
+        python2.7 -m unittest test
+
+   This gives an indication of what methods are exposed to python.
+
+[1]: ../README.md
diff --git a/python/LICENSE b/python/LICENSE
@@ -0,0 +1,16 @@
+This project is licenced under the GNU Lesser General Public Licence
+Version 3 (LGPLv3, http://www.gnu.org/licenses/lgpl.html).
+
+Included third party libraries are released under their respective
+licences, listed below:
+
+Library             Home site                                             License
+Antlr v3.2 	        http://www.antlr.org                                  http://www.antlr.org/license.html
+jlfgr v1.0 	        http://java.sun.com/developer/techDocs/hi/repository/ Included in archive
+commons io v1.4 	  http://commons.apache.org/io/                         http://commons.apache.org/io/license.html
+jcommon v1.0.16 	  http://www.jfree.org/jcommon/                         http://www.gnu.org/licenses/lgpl.html
+jfreechart v1.0.13 	http://www.jfree.org/jfreechart/                      http://www.gnu.org/licenses/lgpl.html
+EasyMock v3.0 	    http://easymock.org/ 	                                http://easymock.org/License.html
+CgLib v2.2 	        http://cglib.sourceforge.net/ 	                      http://www.apache.org/foundation/licence-FAQ.html
+Objenesis v1.2 	    http://objenesis.googlecode.com/svn/docs/index.html 	http://objenesis.googlecode.com/svn/docs/license.html
+ASM v3.3.1 	        http://asm.ow2.org/index.html 	                      http://asm.ow2.org/license.html
diff --git a/python/Makefile b/python/Makefile
@@ -0,0 +1,12 @@
+PREFIX=/usr/local
+
+build_py:
+	cd .. ; make
+	python2.7 setup.py build
+
+test: build_py
+	python2.7 -m unittest tests
+
+install: build_py
+	python2.7 setup.py install --prefix=$(PREFIX)
+
diff --git a/python/NOTES.md b/python/NOTES.md
@@ -0,0 +1,54 @@
+Steps to distribute SpatialKappa python package
+===============================================
+
+Testing in Test PyPi repository
+-------------------------------
+
+1. Test package
+```
+python2 setup.py test
+```
+
+2. Build package
+```
+rm -Rf build/*
+rm -Rf dist/*
+python setup.py sdist bdist_wheel
+```
+
+3. Upload to the Test PyPi repository
+```
+twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+```
+
+4. Create virtual environment https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments
+```
+virtualenv SpatialKappa
+source SpatialKappa/bin/activate
+PYTHONPATH=
+```
+
+5. Test in virtual environment
+```
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url=https://pypi.org/simple/  SpatialKappa==2.1.5
+python -m unittest SpatialKappa.tests
+
+```
+
+Distributing in main PyPi repository
+------------------------------------
+
+1. Change `POSTFIX` in `setup.py` to `.rc1` (say)
+
+2. Test and rebuild
+
+```
+python2 setup.py test
+rm -f dist/*
+python setup.py sdist bdist_wheel
+```
+
+3. Upload
+```
+twine upload  dist/*
+```
diff --git a/python/README.md b/python/README.md
@@ -0,0 +1,29 @@
+SpatialKappa
+============
+
+14 September 2012
+
+Copyright © 2012 DemonSoft.org [http://www.demonsoft.org/](http://www.demonsoft.org)
+
+Copyright © 2014 David C Sterratt <david.c.sterratt@ed.ac.uk>
+
+INTRODUCTION
+------------
+
+This project contains an implementation of a syntactic extension of Kappa to allow expression of location and transport in models. A user manual is available [here][manual-link].
+
+Feel free to add bug reports or feature requests [here][bug-link].
+
+ACKNOWLEDGEMENTS
+----------------
+
+The development of Spatial Kappa was funded in part by <a href="http://www.csbe.ed.ac.uk/">SynthSys</a>. SynthSys is a Centre for Integrative Systems Biology (CISB) funded by BBSRC and EPSRC, reference BB/D019621/1.
+
+DISCLAIMER
+----------	
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+[bug-link]: https://github.com/lptolik/SpatialKappa/issues
+[manual-link]: https://github.com/lptolik/SpatialKappa/raw/master/docs/manual/SpatialKappaManual-v2.1.0.pdf
+[1]: python/INSTALL.md