diff --git a/README b/README
deleted file mode 100644
index e69de29..0000000
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4966324
--- /dev/null
+++ b/README.md
@@ -0,0 +1,19 @@
+sicav_sim
+===========
+python-sympy -based scripts for photonics symbolic calculations
+
+Dependencies
+------------
+- python-sympy 'sudo apt install python-sympy'
+
+Test it
+----------
+run in iPython environment to show local variables
+
+```sh
+ipython
+```
+
+```ipython
+run %script
+```