From e6faaef5514d5bcbca7ee5a621f527592066289d Mon Sep 17 00:00:00 2001
From: George Simmons <g.simmons@idems.international>
Date: Wed, 4 Sep 2024 18:33:18 +0100
Subject: [PATCH] update README

---
 README.md | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c4360fa..d08b56e 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,25 @@
-# population-modeling-py
+# Psymple
 
-## Description
-This is a population modelling package.
+`psymple` is a Python package desinged for general complex systems modelling. A complex system is a dynamic system whose interconnectivity produces non-trivial or unexpected behaviour. Examples of complex systems exist everywhere, from ecological systems, chemical reactions, economic systems, astronomy and even social networks.
 
-## Running tests
+## Installation
 
-Run `python -m unittest`
+`psymple` officially supports Python `3.10` and higher.
+
+The latest version of `psymple` is available on [PyPI](https://pypi.org/project/psymple/) and can be installed with `pip`.
+
+```
+pip install psymple
+```
+
+## Documentation
+
+The latest version of `psymple` documentation can be found [here](https://casasglobal-org.github.io/psymple/).
+
+## Where to start
+
+Familiarisation with the purpose and design principles of `psymple` is recommended before beginning. You can start reading these here: [hybrid systems modelling](https://casasglobal-org.github.io/psymple/overview/modelling_systems/).
+
+Once you're happy, you can start modelling! The best pages to start are [functions](https://casasglobal-org.github.io/psymple/components/functional_ported_objects.md), [differential equations](https://casasglobal-org.github.io/psymple/components/variable_ported_objects.md) and [composite systems](https://casasglobal-org.github.io/psymple/components/composite_ported_objects.md).
+
+If you're interested in how `psymple` implements mathematical principles into `python` objects, the best place to start is [ported objects](https://casasglobal-org.github.io/psymple/mathematics/ported_objects.md).