y_nelson 2.0.8 → 2.1.0

data/YNelson_&_YPetri_User_Manual.lyx

@@ -0,0 +1,1037 @@
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass article
+\use_default_options false
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding auto
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\spacing single
+\use_hyperref false
+\papersize default
+\use_geometry true
+\use_amsmath 1
+\use_esint 1
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine natbib_authoryear
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\leftmargin 2.2cm
+\topmargin 3cm
+\rightmargin 2.2cm
+\bottommargin 3cm
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Title
+YNelson & YPetri – User Manual
+\end_layout
+
+\begin_layout Part*
+What is YNelson
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+\color blue
+YNelson
+\family default
+\color inherit
+ is a Ruby library (gem) providing the domain model and simulator of 
+\emph on
+\color green
+Nelson nets
+\emph default
+\color inherit
+, and the domain-specific language (DSL) to handle them.
+ A 
+\emph on
+\color green
+Nelson net
+\emph default
+\color inherit
+ is a cross between a 
+\emph on
+\color green
+Petri net
+\emph default
+\color inherit
+, and a 
+\emph on
+\color green
+ZZ structure
+\emph default
+\color inherit
+ (as described by Ted Nelson, ...).
+ In accordance with this, 
+\family typewriter
+YNelson
+\family default
+ is a combination of two major dependencies: 
+\family typewriter
+\color blue
+YPetri
+\family default
+\color inherit
+ gem, providing the the domain model of Petri nets, and 
+\family typewriter
+\color blue
+Yzz
+\family default
+\color inherit
+ gem, providing the domain model of ZZ structures.
+ At the moment being, the focus of the development (and this user manual)
+ is the Petri net model – 
+\family typewriter
+YPetri
+\family default
+.
+ Since 
+\family typewriter
+YNelson
+\family default
+ provides the same interface to the Petri net model as 
+\family typewriter
+YPetri
+\family default
+, this text can also serve as a user manual to plain 
+\family typewriter
+YPetri
+\family default
+.
+ As for the ZZ structures, they are a promising data structure acting as
+ a non-SQL relational database, but their use by YNelson is still under
+ development – ZZ structures are so basic, that it's not clear, how deep
+ in the object model should their usage go.
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+YNelson
+\family default
+ requires Ruby 2.1, and can be installed from the command line by 
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+gem install y_nelson
+\family default
+
+\begin_inset Quotes erd
+\end_inset
+
+.
+ The main dependencies, 
+\family typewriter
+Yzz
+\family default
+ and 
+\family typewriter
+YPetri
+\family default
+, should install automatically, but can be installed manually by 
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+gem install y_petri
+\family default
+
+\begin_inset Quotes erd
+\end_inset
+
+ and 
+\begin_inset Quotes eld
+\end_inset
+
+
+\family typewriter
+gem install y
+\family default
+zz
+\begin_inset Quotes erd
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Part*
+Functional Petri nets
+\end_layout
+
+\begin_layout Standard
+Petri nets were described by C.
+ A.
+ Petri in the middle of 20th century.
+ A Petri net can be used to represent various 
+\begin_inset Quotes eld
+\end_inset
+
+wiring diagrams
+\begin_inset Quotes erd
+\end_inset
+
+ – such as production lines, rail networks, electronic circuits, computer
+ architectures, parallel execution diagrams, or chemical systems.
+ In fact, already Petri himself proposet to use Petri nets for modeling
+ chemical reactions.
+ In other words, chemical network modeling was one of the design goals of
+ Petri nets since their inception.
+\end_layout
+
+\begin_layout Standard
+A Petri net diagram consists of 
+\emph on
+\color green
+places
+\emph default
+\color inherit
+, 
+\emph on
+\color green
+transitions
+\emph default
+\color inherit
+, and 
+\emph on
+\color green
+arcs
+\emph default
+\color inherit
+.
+ Places are typically drawn as circles, transitions as rectangles, and arcs
+ as lines or arrows connecting places and transitions.
+ Petri net places may contain 
+\emph on
+\color green
+tokens
+\emph default
+\color inherit
+.
+ Another word for a number of token in a place(s) is 
+\emph on
+\color green
+marking
+\emph default
+\color inherit
+.
+ In 
+\family typewriter
+YNelson
+\family default
+, the amount of tokens (place's marking) is represented by a number attached
+ to the place.
+ When transitions operate (
+\emph on
+\color green
+fire
+\emph default
+\color inherit
+), tokens are added to or removed from the places, to which the transition
+ is connected.
+ It is the property of Petri nets, that their 
+\emph on
+\color green
+state
+\emph default
+\color inherit
+ is fully expressed by the places' marking – the transitions are completely
+ stateless.
+\end_layout
+
+\begin_layout Standard
+Original Petri nets were 
+\emph on
+\color green
+timeless
+\emph default
+\color inherit
+.
+ In a timeless Petri net, transition firing is a discrete event, whose exact
+ timing is not specified.
+ Instead, a timeless Petri net specifies the conditions, under which a transitio
+n is 
+\emph on
+\color green
+enabled
+\emph default
+\color inherit
+ – 
+\emph on
+allowed 
+\emph default
+to fire, or 
+\emph on
+\color green
+disabled
+\emph default
+\color inherit
+ – is 
+\emph on
+prohibited
+\emph default
+ to fire.
+ Typically, a transition in a timeless Petri net is generally enabled, when
+ its input arcs have enough tokens for firing to happen, though other firing
+ conditions may be specified.
+ Timeless Petri nets are generally used to investigate concurrency – things
+ like race conditions, network congestions, state reachability etc.
+ Interaction with timeless Petri nets is called 
+\emph on
+\color green
+token game
+\emph default
+\color inherit
+.
+\end_layout
+
+\begin_layout Standard
+
+\emph on
+\color green
+Timed Petri nets
+\emph default
+\color inherit
+ operate in time.
+ They specify when (or how rapidly) the transitions firing occurs.
+ (The specification may be of stochastic.) Whereas a timeless Petri net requires
+ the user to play the token game, timed Petri net can be 
+\emph on
+\color green
+executed
+\emph default
+\color inherit
+ in time.
+ Timed Petri nets actually represent a wiring diagram of a dynamic system,
+ from which a set of differential equations describing the system can be
+ derived.
+ Even if the differential equations are not expressed explicitly, execution
+ of a timed Petri net is tantamount to numeric integration of its equivalent
+ DE system.
+\end_layout
+
+\begin_layout Part*
+YPetri object model
+\end_layout
+
+\begin_layout Subsection*
+
+\family typewriter
+Place
+\family default
+, 
+\family typewriter
+Transition
+\family default
+ and 
+\family typewriter
+Net
+\family default
+ class
+\end_layout
+
+\begin_layout Standard
+The main classes of 
+\family typewriter
+YPetri
+\family default
+ object model are 
+\family typewriter
+Place
+\family default
+, 
+\family typewriter
+Transition
+\family default
+, and 
+\family typewriter
+Net
+\family default
+.
+ A 
+\family typewriter
+Net
+\family default
+ instance represents a Petri net, consisting of 
+\family typewriter
+Place
+\family default
+ instances and 
+\family typewriter
+Transition
+\family default
+ instances.
+ 
+\family typewriter
+Net
+\family default
+ class is a (subclass of) 
+\family typewriter
+Module
+\family default
+ class, so places and transitions can simply be defined as its constants.
+ If a transition belongs to a net, all the places connected to it must belong
+ to the same net.
+\end_layout
+
+\begin_layout Standard
+Transitions can be divided into ...
+ s / S, t / T, a / A ...
+ this gives 5 basic types ...
+\end_layout
+
+\begin_layout Subsection*
+
+\family typewriter
+Simulation
+\family default
+ and 
+\family typewriter
+Core
+\family default
+ class
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+Simulation
+\family default
+ class represents a simulation of a particular network, with particular
+ simulation settings.
+ 
+\family typewriter
+Core
+\family default
+ class represents the simulator – a machine that performs the execution
+ of a Petri net.
+ When a simulation instance wants to proceed in time to a next state, it
+ realies on a 
+\family typewriter
+Core
+\family default
+ instance to perform the computation.
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+Simulation
+\family default
+ – Public instance methods
+\end_layout
+
+\begin_layout Standard
+place access:
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+transition access:
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+element access:
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+inital marking access:
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+marking clamp access:
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+marking vector access:
+\end_layout
+
+\begin_layout Standard
+m_vector – as a column vector
+\end_layout
+
+\begin_layout Standard
+m – as an array
+\end_layout
+
+\begin_layout Standard
+place_m – as place => value hash
+\end_layout
+
+\begin_layout Standard
+p_m – as place name => value hash
+\end_layout
+
+\begin_layout Standard
+pm – pretty prints the name => value hash
+\end_layout
+
+\begin_layout Standard
+update_m – modifies the marking vector
+\end_layout
+
+\begin_layout Standard
+marking_vector – as m_vector, for free places only
+\end_layout
+
+\begin_layout Standard
+marking – as m, for free places only
+\end_layout
+
+\begin_layout Standard
+place_marking – as place_m, for free places only
+\end_layout
+
+\begin_layout Standard
+p_marking – as p_m, for free places only
+\end_layout
+
+\begin_layout Standard
+update_marking – as update_m, but the places must be free places only
+\end_layout
+
+\begin_layout Standard
+increment_marking – increments the marking vector with a supplied difference
+ vector (whose positions corresponds to free places)
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+own methods:
+\end_layout
+
+\begin_layout Standard
+firing – returns firing of the indicated tS transitions
+\end_layout
+
+\begin_layout Standard
+t_firing – same as has transition name => firing
+\end_layout
+
+\begin_layout Standard
+pfiring – pretty prints firing
+\end_layout
+
+\begin_layout Standard
+??? flux
+\end_layout
+
+\begin_layout Standard
+??? t_flux
+\end_layout
+
+\begin_layout Standard
+??? pflux
+\end_layout
+
+\begin_layout Standard
+??? gradient
+\end_layout
+
+\begin_layout Standard
+??? p_gradient
+\end_layout
+
+\begin_layout Standard
+??? pgradient
+\end_layout
+
+\begin_layout Standard
+??? delta
+\end_layout
+
+\begin_layout Standard
+??? p_delta
+\end_layout
+
+\begin_layout Standard
+??? pdelta
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+Core class is a bit intimate to YPetri, it is not directly controlled by
+ the user.
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+Core
+\family default
+ – Public class methods
+\end_layout
+
+\begin_layout Standard
+new – constructor
+\end_layout
+
+\begin_layout Standard
+using_simulation_method( symbol, guarded: false ) – constructor
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+Core
+\family default
+ – Public instance methods
+\end_layout
+
+\begin_layout Standard
+guarded?
+\end_layout
+
+\begin_layout Standard
+delta_timeless
+\end_layout
+
+\begin_layout Standard
+delta_tS
+\end_layout
+
+\begin_layout Standard
+delta_ts
+\end_layout
+
+\begin_layout Standard
+firing_vector_tS
+\end_layout
+
+\begin_layout Standard
+increment_marking_vector( delta )
+\end_layout
+
+\begin_layout Standard
+assignment_transitions_all_fire!
+\end_layout
+
+\begin_layout Subsection*
+
+\family typewriter
+Net::State
+\family default
+, state features, and 
+\family typewriter
+Record
+\end_layout
+
+\begin_layout Standard
+A particular Petri net, as mentioned earlier, may have state, which is entirely
+ given by the marking vector of its places.
+ This state is represented in YPetri by Net::State class.
+ Furthermore, a net in a particular state can have various features defined
+ on it.
+ A feature is represented by 
+\family typewriter
+Net::State::Feature
+\family default
+ class.
+ At the moment being, following features are supported: 
+\family typewriter
+Marking
+\family default
+, 
+\family typewriter
+Firing
+\family default
+, 
+\family typewriter
+Flux
+\family default
+, 
+\family typewriter
+Gradient
+\family default
+ and 
+\family typewriter
+Delta
+\family default
+.
+ For each feature, measurement can be performed on a net in a particular
+ state, returning the feature's value.
+ A collection of such features is called a feature set, and is represented
+ by 
+\family typewriter
+Net::State::Features
+\family default
+ class in 
+\family typewriter
+YPetri
+\family default
+.
+ Measurement performed for a particular feature set results in a 
+\family typewriter
+Record
+\family default
+ instance.
+ Record is an Array subclass, but it remembers the features to which the
+ stored values correspond.
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+Feature
+\family default
+ – Public instance methods
+\end_layout
+
+\begin_layout Standard
+extract_from( target, **nn ) – extracts the feature from the given target
+ object.
+ The target object must own a net state for the same net, for which this
+ state feature was defined.
+\end_layout
+
+\begin_layout Standard
+label – label for this feature (to use in graphics etc.)
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+Features
+\family default
+ – Public class methods
+\end_layout
+
+\begin_layout Standard
+new – Constructor / instance reference
+\end_layout
+
+\begin_layout Standard
+marking, flux, firing, gradient, delta – Features instance reference
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+Features
+\family default
+ – Public instance methods
+\end_layout
+
+\begin_layout Standard
+extract_from( target, **nn ) - extracts the feature set from a given target,
+ returning a Record instance.
+\end_layout
+
+\begin_layout Standard
+new_record( values ) – Record instance constructor
+\end_layout
+
+\begin_layout Standard
++, -, * – same as for arrays
+\end_layout
+
+\begin_layout Standard
+labels – feature labels
+\end_layout
+
+\begin_layout Standard
+reduce_features – 
+\end_layout
+
+\begin_layout Standard
+marking, flux, firing, gradient, delta – feature reduction
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+State
+\family default
+ -- Public class methods
+\end_layout
+
+\begin_layout Standard
+feature -- Feature instance reference
+\end_layout
+
+\begin_layout Standard
+features – Features (feature set) instance reference
+\end_layout
+
+\begin_layout Standard
+marking, flux, firing, gradient, delta – Features instance reference
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+State
+\family default
+ -- Public instance method
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+Record
+\family default
+ -- Public class methods
+\end_layout
+
+\begin_layout Standard
+features – returns the features to which the record values correspond
+\end_layout
+
+\begin_layout Standard
+load( values ) - constructs a new Record object from a given collection
+ of values.
+\end_layout
+
+\begin_layout Standard
+Record -- Public instance methods
+\end_layout
+
+\begin_layout Standard
+marking, firing, flux, gradient, delta – feature extraction from a record
+\end_layout
+
+\begin_layout Standard
+fetch( feature ) – single feature extraction from a record
+\end_layout
+
+\begin_layout Standard
+dump – should it be renamed to #to_a?
+\end_layout
+
+\begin_layout Standard
+print – pretty prints the records with feature names
+\end_layout
+
+\begin_layout Standard
+state( marking_clamps: {} ) – returns the state instance implied by the
+ record and the supplied complementary set of marking clamps
+\end_layout
+
+\begin_layout Standard
+reconstruct( **settings ) – reconstructs a simulation instance from the
+ record and the given simulation settings
+\end_layout
+
+\begin_layout Standard
+euclidean_distance( other ) – computes the Euclidean distance to another
+ record with the same feature set.
+\end_layout
+
+\begin_layout Subsection*
+
+\family typewriter
+DataSet
+\family default
+ class
+\end_layout
+
+\begin_layout Standard
+...
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+DataSet
+\family default
+ -- Public instance methods
+\end_layout
+
+\begin_layout Standard
+net – a dataset knows its net
+\end_layout
+
+\begin_layout Standard
+reduce_features – selects certain columns (features) of a dataset.
+\end_layout
+
+\begin_layout Standard
+slice – since DataSet is a Hash subclass, YSupport's Hash#slice method is
+ available to it, and can be used to select only certain rows (records)
+ of a dataset.
+\end_layout
+
+\begin_layout Standard
+marking, firing, flux, gradient, delta – additional convenience methods
+ for selecting particular columns and rows from the dataset
+\end_layout
+
+\begin_layout Standard
+record( event ) – returns the record instance for a given recorded key
+\end_layout
+
+\begin_layout Standard
+floor( event ), ceiling( event ) – given a key value, they return the nearest
+ record actually present in the dataset – floor returns the nearest lower
+ or equal, ceiling the nearest higher or equal record.
+\end_layout
+
+\begin_layout Standard
+interpolate( event ) – Interpolates a record for a given key.
+\end_layout
+
+\begin_layout Standard
+print – pretty-prints the dataset
+\end_layout
+
+\begin_layout Standard
+plot – plots the dataset
+\end_layout
+
+\begin_layout Standard
+resample – resamples the recording
+\end_layout
+
+\begin_layout Standard
+series – returns the data series for the specified features
+\end_layout
+
+\begin_layout Standard
+timed? – whether the dataset type is timed
+\end_layout
+
+\begin_layout Standard
+reconstruct( event:, **settings ) – reconstructs a simulation instance for
+ a given key
+\end_layout
+
+\begin_layout Subsection*
+
+\family typewriter
+YPetri::World
+\family default
+ and 
+\family typewriter
+YPetri::Agent
+\family default
+ class
+\end_layout
+
+\begin_layout Standard
+
+\family typewriter
+YPetri::World
+\family default
+ is the object space where places, transitions, and nets live.
+ (Originally, this class was named 
+\family typewriter
+Workspace
+\family default
+, but 
+\family typewriter
+World
+\family default
+ is shorter.) As for 
+\family typewriter
+YPetri::Agent
+\family default
+ class, it represents the user and acts as user proxy to 
+\family typewriter
+YPetri::World
+\family default
+ instance.
+ 
+\family typewriter
+YPetri::Agent
+\family default
+ does not encapsulate 
+\family typewriter
+YPetri
+\family default
+ as completely, as the Law of Demeter might require, but it does one very
+ useful thing: It defines the top-level DSL commands (methods) that are
+ available upon calling '
+\family typewriter
+include YPetri
+\family default
+' or '
+\family typewriter
+include YNelson
+\family default
+'.
+\end_layout
+
+\end_body
+\end_document