README.md in y_petri-2.1.18 vs README.md in y_petri-2.1.20

@@ -1,27 +1,94 @@
 # YPetri
 
-y_petri is a Petri net domain model and simulator
+`YPetri` is a domain model and a simulator of _functional_ _Petri_ _nets_,
+a family of Petri nets, whose transitions have functions attached to them.
 
-## Installation
+## Usage
 
-Add this line to your application's Gemfile:
+`YPetri` provides a _domain_ _specific_ _language_ (DSL), that can be loaded by:
+```ruby
+  require 'y_petri'
+  include YPetri
+```
+Now, one can create places:
+```ruby
+  A = Place()
+  B = Place()
+  places.names # you can shorten this to #pn
+  #=> [:A, :B]
+  # Setting their marking:
+  A.marking = 2
+  B.marking = 5
+```
+And transitions:
+```ruby
+  A2B = Transition stoichiometry: { A: -1, B: 1 }
+  #=> #<Transition: A2B (tS) >
+  A2B.stoichiometry
+  #=> [-1, 1]
+  A2B.s
+  #=> {:A=>-1, :B=>1}
+  A2B.arcs.names
+  #=> [:A, :B]
+  A2B.timeless?
+  #=> true
+  A2B.enabled?
+  #=> true
+```
+Explanation of the keywords: _arcs_, _enabled_ are standard Petri net terms,
+_stoichiometry_ means arcs with the amount of tokens to add / take from the
+connected places when the transition fires, _timeless_ means that firing of
+the transition is not defined in time.
 
-    gem 'y_petri'
+We can now play the _token_ _game_:
+```ruby
+  places.map &:marking
+  #=> [2, 5]
+  A2B.fire!
+  places.map &:marking
+  #=> [1, 6]
+  A2B.fire!
+  places.map &:marking
+  #=> [0, 7]
+```
 
-And then execute:
+## Advanced usage
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install y_petri
-
-## Usage
-
-y_petri can be used either interactively (in irb with
-'include YPetri'), or from another program. YPetri::Manipulator
-provides the command interface.
+A Petri net is mostly used as a wiring diagram of some real-world system. Such
+Petri net can then be used to generate (implicitly or explicitly) a more specific
+simulation of that real-world system. This is represented by `YPetri::Simulation`
+class. If a Petri net with only _timed_ transitions is considered, it can then
+be used to generate (implicitly or explicitly) a system of ordinary differential
+equations (ODE). A Simulation class instance generated from such Petri net can
+then be used to eg. solve the initial value problem by numeric integration of the
+ODE system using one of the available numerical methods:
+```ruby
+  # Start a fresh irb session!
+  require 'y_petri'
+  include YPetri
+  A = Place default_marking: 0.5
+  B = Place default_marking: 0.5
+  A_pump = Transition s: { A: -1 }, rate: proc { 0.005 }
+  B_decay = Transition s: { B: -1 }, rate: 0.05
+  net
+  #=> #<Net: name: Top, 2pp, 2tt >
+  run!
+```
+Simulation can now be accessed through `simulation` DSL method:
+```ruby
+  simulation
+  #=> #<Simulation: time: 60, pp: 2, tt: 2, oid: -XXXXXXXXX>
+  simulation.settings
+  #=> {:method=>:pseudo_euler, :guarded=>false, :step=>0.1, :sampling=>5, :time=>0..60}
+  print_recording
+```
+If you have `gnuplot` gem installed properly, you can view plots:
+```ruby
+  plot_state
+  plot_flux
+```
+So much for the demo for now! Thanks for trying YPetri!
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)