Added Requirements.md

- Added a document describing requirements for the system
- Updated README - removed parts that were moved to other documents

DevelopmentNotes/Requirements.md

@@ -0,0 +1,70 @@
+#  Requirements
+
+System to be designed:
+
+> Set of libraries and tools for computer aided design of systems thinking
+  models.
+
+## System Concerns
+
+### Purpose
+
+1. Aid in visual design of a domain model (stock-flow, causal map, …).
+2. Simulation of a model.
+3. Comparison of different models or different versions of a model.
+4. Composition of meta-models.
+5. Aid in reasoning about a domain model by deriving/computing additional
+   information from the model.
+6. Creation of clear, understandable graphical representation of the domain model.
+
+### Needs
+
+**User-oriented needs**
+
+1. User entered content – the creation – is holy.
+    - The content should be preserved as-is and provided to the user in an
+      understandable and processable form when asked for.
+2. Ability to design a model interactively and iteratively.
+    - User must be able to explore different model versions easily.
+    - User must be able to revert its actions without losing any of entered
+      content.
+    - User must be able to see the evolution of the model.
+3. User must be allowed to make mistakes without harm to the user and to the creation.
+    - Alternative wording: User must be allowed to do experiments and to be playful.
+    - User must know where they made a mistake.
+    - User should receive a hint what to do to prevent the mistake,
+      if possible.
+
+**Creation-oriented needs**
+
+4. Users creation should have assured durability and should not be locked-in.
+   by a particular version of the system.
+    - The persisted artefacts of user's creation must be stored in a format
+      that is open and documented.
+    - Inspection of the structure of stored archive should be reasonably
+      possible with third-party tools that are not based on the Poietic System.
+      [^1]
+
+[^1]: For example a relational database storage or a directory with a collection
+      of CSV files satisfies this requirement.
+
+
+### Maintainability and Evolvability
+
+1. Continuation of the system is an important feature.
+2. It must be easy to add new object types and to extend objects with new
+   components.
+3. It must be possible to inspect the design during runtime.
+
+**Principles governing the evolution of the system:**
+
+4. The metamodel and the constraints must be explicit and their description must
+   be available during runtime.
+5. The system should be implemented in a transparent way and it should be
+   reasonably easy to explain its functioning.
+6. The system should not be tightly coupled with the programming language the
+   system is implemented in.
+    - It should be reasonably straightforward to rewrite the system or its
+      subsystems in another programming language.
+
+

README.md

@@ -1,11 +1,11 @@
 # Poietic
 
-A modelling and simulation toy toolkit for systems dynamics.
+A modelling and simulation toy toolkit for systems thinking and systems dynamics.
 
 Function:
 
-- Creation and iterative design of systems dynamics models
-- Simulation of systems dynamics models
+- Creation and iterative design of systems dynamics models.
+- Simulation of systems dynamics models.
 
 Focus and approach:
 
@@ -24,19 +24,22 @@ Focus and approach:
 Current:
 
 - [Stock and Flow](https://en.wikipedia.org/wiki/Stock_and_flow) model
-    - Implemented nodes: Stock, Flow, Auxiliary
+    - Implemented nodes: Stock, Flow, Auxiliary, Graphical Function
     - Stocks can be either non-negative or can allow negative values
     - Included [Euler](https://en.wikipedia.org/wiki/Euler_method) and [RK4](https://en.wikipedia.org/wiki/Runge–Kutta_methods) solvers
 - Simple arithmetic expressions (formulas)
     - Built-in functions: abs, floor, ceiling, round, power, sum, min, max
-- Export to [Graphviz](https://graphviz.org) dot files.
 - Whole editing history is preserved.
 - Editing is non-destructive and can be reversed using undo and
   redo commands.
+- Exports:
+    - [Graphviz](https://graphviz.org) dot files.
+    - Export to CSV.
+    - Charts to [Gnuplot](http://gnuplot.info)
 
 Planned:
 
-- More useful built-in functions and variables.
+- More useful built-in functions and variables for the Stock and Flow model.
 - Sub-systems.
 - API for GUI applications.
 - Visual layout.
@@ -134,43 +137,18 @@ poietic run
 
 ## Development
 
-This is a hobby project. A toy.
+This is a sketch of a toy.
 
-It is still a prototype, a sketch if you like. Compare it to painter's canvas
-at the beginning - rough outlines with a pencil.
-
-Different parts reflect different stages and different understanding of the
-problem and its implementation. As the understanding of the problem improves,
-the parts are refactored. However, the primary focus right now is on having
-some basic functionality of the whole system without seriously annoying the
-users.
-
-Principles:
-
-- User entered content is holy. Should be preserved as-is and provided to the
-  user in an understandable and processable form when asked for.
-- User is allowed to make mistakes.
+More information about the development can be found in documents in the
+[DevelopmentNotes](DevelopmentNotes) directory.
 
 Further reading:
 
+- [Requirements](DevelopmentNotes/Requirements.md) document in the
+  DevelopmentNotes folder.
 - [Technical Debt](DevelopmentNotes/TechnicalDebt.md) document in the
   DevelopmentNotes folder.
 
-Error handling:
-
-- There should be a strict distinction between a programming error and user error:
-    - Programming errors must not happen at any cost, they are guarded by 
-      preconditions and asserts. Programming errors are errors that prevent
-      further continuation of the program in a meaningful and consistent way.
-      Example: Errors with user input are not programming errors.
-    - User errors must be handled and presented to the user.
-- Errors should be descriptive and it is recommended that they are accompanied
-  with a hint how to remove them.
-- If there is a potential for multiple user errors, then as many errors should be
-  gathered as possible and presented to the user.
-- Context of the error must be included if known, for example an object that
-  caused the error.
-
 ## Author
 
 - [Stefan Urbanek](mailto:stefan.urbanek@gmail.com)