y_nelson 2.1.0 → 2.3.0

data/YNelson_&_YPetri_User_Manual.lyx

@@ -1,1037 +0,0 @@
-#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