Check-in [789c3e57bb]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Checkpoint on writing a howto document for micca.
Timelines: family | ancestors | descendants | both | micca-develop
Files: files | file ages | folders
SHA1:789c3e57bbe016dd829cde31ed37d0989e8332f7
User & Date: andrewm 2019-02-23 08:56:08
Context
2019-02-23
16:24
Checkpoint on how to translate using micca document. Finished translating dynamics part. check-in: 604404cd7c user: andrewm tags: micca-develop
08:56
Checkpoint on writing a howto document for micca. check-in: 789c3e57bb user: andrewm tags: micca-develop
2019-02-17
17:57
Checkpoint in document on how to translate a model with micca. check-in: 43a8ae7699 user: andrewm tags: micca-develop
Changes

Changes to micca/doc/howto/Makefile.

33
34
35
36
37
38
39




40
41
42
43
44
45
46

47
48
49

50
51
52
53
54
55
56
57
58
59
...
101
102
103
104
105
106
107

108
109
110
111
112
113
114
115
	micca-translation.uxf\
	$(NULL)

IMAGES =\
	$(patsubst %.uxf,$(IMAGEDIR)/%.pdf,$(DIAGRAMS))\
	$(NULL)





PDF 	=\
     	$(patsubst %.txt,%.pdf,$(DOCSRC))\
     	$(NULL)

CLEANFILES =\
	$(IMAGES)\
	$(PDF)\

	$(NULL)

A2XOPTS =\

	$(NULL)

#	--verbose


ATANGLEOPTS =\
	$(NULL)

DBLATEX_PARAMS =\
	bibliography.numbered=0\
................................................................................
	$(RM) $(CLEANFILES)

$(PDF) : $(DOCSRC) $(DOCPARTS) $(EXTRAS) $(IMAGES)

%.pdf : %.txt
	a2x $(A2XOPTS) --doctype=article  --format=pdf\
	    $(ASCIIDOC_OPTS) $(DBLATEX_OPTS) $<


%.pdf : %.uxf
	umlet -action=convert -format=pdf\
		-filename=$< -output=$(basename $@)

#
# vim: sw=8 ts=8 sts=8 noexpandtab
#







>
>
>
>







>



>


<







 







>








33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

58
59
60
61
62
63
64
...
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
	micca-translation.uxf\
	$(NULL)

IMAGES =\
	$(patsubst %.uxf,$(IMAGEDIR)/%.pdf,$(DIAGRAMS))\
	$(NULL)

GENIMAGES=\
     	$(patsubst %.txt,%__*.png,$(DOCSRC))\
	$(NULL)

PDF 	=\
     	$(patsubst %.txt,%.pdf,$(DOCSRC))\
     	$(NULL)

CLEANFILES =\
	$(IMAGES)\
	$(PDF)\
     	$(GENIMAGES)\
	$(NULL)

A2XOPTS =\
	--verbose\
	$(NULL)




ATANGLEOPTS =\
	$(NULL)

DBLATEX_PARAMS =\
	bibliography.numbered=0\
................................................................................
	$(RM) $(CLEANFILES)

$(PDF) : $(DOCSRC) $(DOCPARTS) $(EXTRAS) $(IMAGES)

%.pdf : %.txt
	a2x $(A2XOPTS) --doctype=article  --format=pdf\
	    $(ASCIIDOC_OPTS) $(DBLATEX_OPTS) $<
	$(RM) $(GENIMAGES)

%.pdf : %.uxf
	umlet -action=convert -format=pdf\
		-filename=$< -output=$(basename $@)

#
# vim: sw=8 ts=8 sts=8 noexpandtab
#

Changes to micca/doc/howto/dynamics.txt.

1
2
3




4


























































































































































































































































































5
== Translating dynamics
Translating dynamics
































































































































































































































































































// vim:syntax=asciidoc:

<

>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1

2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
== Translating dynamics


Translating the dynamics of the model requires the least amount of
transformation of the three model facets.
The semantics of the Moore state models used in XUML are directly
mapped to `micca` commands.

For classes with a state model,
add a `statemodel` command to its class definition:

----
class LightBulb {
    # light bulb attributes, etc.

    statemodel {
        # Statements that define the states and transitions
        # of the class state model.
    }
}
----

For brevity in the following examples,
we assume the `statemodel` command is contained within the appropriate
`class` definition script.

Two things must be defined for a state model.
The states must be defined and the code to execute when the state
is entered is part of that definition.
In this section,
we do not discuss translating the code for state activities.
We consider that in the next section.
To specify a state,
`micca` uses the `state` command.

Consider a simple light bulb.

["plantuml"]
----
@startuml
hide empty description

[*] --> Off
Off --> On : Turn on
On --> Off : Turn off

Off : ~# code for Off state
On : ~# code for On state
@enduml
----

The `micca` commands for the states in this diagram are as follows.

----
statemodel {
    state Off {} {
        # code to execute when the Off state is entered.
    }

    state On {} {
        # code to execute when the On state is entered.
    }
}
----

Here we have defined two states, `Off` and `On`.
The `state` command takes three arguments:

. The name of the state.
. The parameters of the state.
. The body of ``C'' code to execute when the state is entered.

State activity parameters are carried along in the event that
causes the transition _into_ the state.
We discuss states with parameters more below.
Here there are no parameters to the state activity,
so we specify them as empty ({}).

The other aspect of a state model translation is to specify all the state
transitions.
The starting point for translating the state transitions is,
naturally enough, the transition matrix of each state model.
Consider the following simple transition matrix.

[options="header",cols="3*^",title="Light Bulb State Transitions",width="50%"]
|=====
|State / Event  |Turn off       |Turn on
|Off            |IG             |On
|On             |Off            |IG
|=====

The `micca` command to specify transitions is `transition`.
The `transition` command specifies one cell of the transition matrix.
We can complete the translation of this state model as follows.

----
statemodel {
    state Off {} {
        # code to execute when the Off state is entered.
    }

    state On {} {
        # code to execute when the On state is entered.
    }

    transition Off - Turn_off -> IG
    transition Off - Turn_on -> On
    transition On - Turn_off -> Off
    transition On - Turn_on -> IG
}
----

[NOTE]
Note that `micca` does not have any ordering requirements on the
`state` or `transition` commands.
You can put all the `transition` command first or mix them around
in any way you wish.
One common organization is to list the _outgoing_ transitions
for a state immediately after the `state` command defining the state.

=== Default transitions

The state model diagram show previously,
only shows transitions to states.
It does not show ignored (IG) or can't happen (CH) pseudo-transitions.
In our translation of the example,
we explicitly stated all the IG transitions.
This can be tedious if there are a lot of these types of transitions
to encode.
So, `micca` allows you to set a default transition.
Any transition _not_ mentioned in a `transition` command is assigned
the default transition.

Normally, the default transition is *CH* (for some very good reasons
that catches many errors).
However,
some state models, assigners in particular, 
ignore most event that do not cause an explicit transition to a state.
Our light bulb example also ignores events.
To change the default transition,
use the `defaulttrans` command.
Our light bulb example might have been written as:

----
statemodel {
    defaulttrans IG

    state Off {} {
        # code to execute when the Off state is entered.
    }
    transition Off - Turn_on -> On

    state On {} {
        # code to execute when the On state is entered.
    }
    transition On - Turn_off -> Off
}
----

Some find this manner of specifying the state model clearer.
Note also the `defaulttrans` command may appear anywhere and need not
be the first command in the state model definition.

=== Initial state

All state models must specify an initial state in which to start.
For our light bulb example,
the initial state is *Off*.
This is indicated by the state model graphic having a black circle
(the pseudo-initial state) connected to the *Off* state by an unlabeled
arrow.

The `initialstate` command is used to specify the initial starting state
for a state model.
If no `initialstate` command is specified in the state model definition,
then `micca` chooses the first state defined as the initial state.
It is usually wise to specify the initial state, if only for documentation
purposes and to make sure things don't go wrong if the order of
state definitions is changed.
Again,
our light bulb example might have bee written as:

----
statemodel {
    initialstate Off
    defaulttrans IG

    state Off {} {
        # code to execute when the Off state is entered.
    }
    transition Off - Turn_on -> On

    state On {} {
        # code to execute when the On state is entered.
    }
    transition On - Turn_off -> Off
}
----

==== Initial state semantics

How initial states get handled is fundamentally an analysis concern.
However,
it is worth repeating here how activities associated with initial states
are handled.
Sometimes, problems with initial state activity execution are
assumed to be translation problems.

There are two ways to create class instances:

. Synchronously, where a state activity requests a class instance be
    created and that instance exists when the invocation of the request
    function completes.
    If that class has a state model,
    the newly created instance is placed in an initial state according to:
    .. the default initial state defined in the `statemodel` script, or
    .. the _initial state requested by the state activity_ performing
        the synchronous creation.
        It is possible when the instance creation is operation is invoked,
        to request a specific state into which the newly created instance
        is to be placed.
        This feature is _not_ often used, but it does exist and it
        has useful cases where it is needed.

+
Regardless of how the initial state of a synchronously created
instance is determined,
the state activity associated with the initial state *is not executed*.

. Asynchronously, where a state activity sends a creation event.
    After signaling a creation event,
    the state activity that performed the signaling continues
    executing and the new class instance is created at some later time.
    When the creation event is eventually dispatched,
    the class instance is created in the _pseudo-initial state_, and the
    creation event causes a transition out of that state.
    There is only one pseudo-initial state, but there may be many
    events that cause a transition out of it (and any event which
    does not cause a transition out of the pseudo-initial state
    will cause a *CH* transition if it is used as a creation event).
    When the transition out of the pseudo-initial state happens
    a new state is entered,
    and the *state activity of the new state is executed*.

We discuss how to specify creation events below.

=== Final states

The lifecycle of some classes is over when they enter a certain state.
Consider the state model below.

["plantuml"]
----
@startuml
hide empty description

[*] --> Starting
Starting --> Requesting : Request
Requesting --> Requesting : Request
Requesting --> Finished : Done
Finished --> [*]

Starting : ~# code for Starting state
Requesting : ~# code for Requesting state
Finished : ~# code for the Finishing state
@enduml
----

----
statemodel {
    # state and transition definitions

    final Finished
}
----

=== Event definitions
Event definitions

=== Polymorphic events
Polymorphic events

=== Creation events
Creation events

==== Assigner state models
Assigner state models



// vim:syntax=asciidoc:

Changes to micca/doc/howto/intro.txt.

99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
...
186
187
188
189
190
191
192




193
194
195
196
197
198
199
  ** The skill sets required to be a good Translator are quite different than
    those required of a good Analyst.
    Specialization can increase the efficiency of accomplishing the work.

+
Experience has shown that all models have small logical inconsistencies
and errors in them before they are translated.
Such errors or not an indictment of the Analyst's talents.
It is important that the Translator and the Analyst communicate
and correct the inevitable errors that will be found in the first
attempts to translate the model.
The separation of analysis from translation is intended to separate the problem
essentials from the implemenatation artifacts.
It is *not* intended to erect a virtual wall across which political battles can
be waged with one side contending the models can't be made to run
and the other side contending that they are perfectly translatable.

=== Available targets
Available targets

=== Complete model

Before translation can be begin,
................................................................................
    It is suggested that ignored events be justified as to the reasoning
    for ignoring them.
  - A description of each state and the role it plays in the lifecycle
    of the class.
  - A state activity description of the processing for each state.
    The processing should be described in an unambiguous action language
    or in action data flow diagrams.




* A set of instance operation descriptions for each class
    that defines them, to include:
  - A description of the function and interface of the operation.
  - The processing performed by the operation in terms of action language
    or a data flow diagram.
* A set of domain operation descriptions that include:
  - A written description of the operation function and interface.







|







|







 







>
>
>
>







99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
...
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
  ** The skill sets required to be a good Translator are quite different than
    those required of a good Analyst.
    Specialization can increase the efficiency of accomplishing the work.

+
Experience has shown that all models have small logical inconsistencies
and errors in them before they are translated.
Such errors are not an indictment of the Analyst's talents.
It is important that the Translator and the Analyst communicate
and correct the inevitable errors that will be found in the first
attempts to translate the model.
The separation of analysis from translation is intended to separate the problem
essentials from the implemenatation artifacts.
It is *not* intended to erect a virtual wall across which political battles can
be waged with one side contending the models can't be made to run
and the other side contending that they are perfectly clear and consistent.

=== Available targets
Available targets

=== Complete model

Before translation can be begin,
................................................................................
    It is suggested that ignored events be justified as to the reasoning
    for ignoring them.
  - A description of each state and the role it plays in the lifecycle
    of the class.
  - A state activity description of the processing for each state.
    The processing should be described in an unambiguous action language
    or in action data flow diagrams.
* A state model for each relationship that requires an assigner
  to serialize the creation of an instance of the relationship.
  The contents of this state model are the same as for a state model
  of a class lifecycle.
* A set of instance operation descriptions for each class
    that defines them, to include:
  - A description of the function and interface of the operation.
  - The processing performed by the operation in terms of action language
    or a data flow diagram.
* A set of domain operation descriptions that include:
  - A written description of the operation function and interface.

Changes to micca/doc/howto/marking.txt.

1
2
3












4
5











6









7
8








































































9

10
11
12
13

14
15
16

17
18




19
20

21
22



23



24



































25
26
27
== Model marking

* marking is analogous to semantic analysis for a language compiler.













* model compiler does not generate the model you should have written.






















* mark instance creation/deletion -- both sync and async








































































* mark attributes as read/written

  - reading/writing of referential attributes
* mark relationships traversed and direction

* mark instance access by attribute values vs. relationship navigation


* elide identifying attributes
  - when you can and when you cannot


* use of class operations





=== Optimizations


* composition of related instances







* generalization relationships union/non-union





































// vim:syntax=asciidoc:


|
>
>
>
>
>
>
>
>
>
>
>
>

<
>
>
>
>
>
>
>
>
>
>
>

>
>
>
>
>
>
>
>
>

<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
|
<

<
>

|
<
>

<
>
>
>
>

<
>

<
>
>
>

>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

114

115
116
117

118
119

120
121
122
123
124

125
126

127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
== Model marking

When a language compiler transforms source code into something that
is executable,
it typically is structured to analyze the code in a series of
phases on the path to producing something executable by a computer.
The techniques used are many and varied.
Some compilers produce machine specific assembly code or even skip
the assembly step and produce machine code directly.
Other compilers are targeted at virtual machines and produce code
that is then interpreted (or further compiled) at run time to
execute the program.
The many different approaches all have trade-offs,
yielding different characteristics,
that make them more or less suitable for a particular problem.


Most compilers use a semantic checking and analysis phase.
During this phase the compiler insures that language statement which are
syntactically correct are actually meaningful within the rules of
the way the language works.
In all language systems,
it is possible to have correct statements in the language that have
no meaning.
For example,
if the language requires that variables be declared before they are used,
an expression that refers to an undeclared variable has no meaning
even if that expression was correctly composed of valid language tokens..

Language compilers also typically examine the execution characteristics
of the program being compiled.
Internally, a flow graph of execution is often generated and many of
the optimizations performed by a compile are operations that transform
a flow graph into a semantically equivalent one that minimizes
some aspect of the resulting code.
For example it is possible to examine the flow graph of a function
that contains a loop construct and determine that some code piece
may be _lifted_ outside of the loop and still achieve the same result.


It should come as no surprise then that
translating an XUML model requires analogous examination.
Fortunately,
the situation is much simpler for a model than a compiled language.
For the case of a model,
a single pass over the processing description of the activities
is sufficient to generate the introspection we need.
We call this analysis of the model processing with the goal of
characterizing the operation of the model as _marking the model_.

=== Semantic considerations

It is important to understand the purpose of the model marking.
The first step of model translation is to cast the platform
independent model into a platform dependent model.
`Micca` operates off of a platform dependent specification of
the domain properties
and supplies a specific set of mechanisms by which model semantics
may be realized as an actual implementation targeted at a
specific scale of computing.
In the process of transforming the model into a platform specific
description,
logical aspects of the model must be made concrete in terms
supported by the platform specific model.

For example,
models specify the data types of attributes as a set of values.
In platform specific terms,
we must decide how that value set can be represented as a ``C''
data type, since our platform programming language is ``C''.
Usually the decision is easy and obvious, and
we choose a data type that can represent the platform independent
value set.

It is also the case,
that most models do not make full use of all the capablities
implied by the platform independent modeling language.
This creates situations where optimizations are available to meet
the specific use case of the model rather than necessarily providing
a general capability that would support any model.
For example,
if the model activities never access the referential attributes
of a class in a descriptive manner,
then such attributes need not be stored since the underlying
platform specifics supplied by `micca` handle implementing
the referential implications of the modeling language.

The importance of model marking is then to gather the information
about what the activities of the model actually do so as to make
informed decisions about how to map those activities onto the
platform specific mechanisms provide by `micca`.

=== Model metadata

The purpose of closely examining the processing performed by a model
is to characterize the computations the model actually performs
as opposed to the those computations that the modeling language
might support.
In this section,
we specify the model metadata that needs to be collected during the model
marking phase.

==== Class metadata

For classes, we are interested in determining if any activity in the
model does the following:

* Create an instance, either synchronously or asynchronously via a
  creation event.
* Delete an instance either synchronously or asynchronously as a result
  of entering a final state.
* Query the set of class instances based solely upon the values of identifying
  attributes.
* Query the set of class instances based upon the values of non-identifying
  attributes.



==== Attribute metadata

For class attributes,

we wish to know:


* Any attribute that is read.
* Any attribute whose value is updated.
* Any mathematically dependent attribute that is updated
  (this is an analysis error).


==== Relationship metadata


For relationships,
we are interested in the navigation of relationships by the activities
in the model. Specifically:

* The direction of navigation of a relationship between the participating
  classes.
* Navigating generalization relationships from supertype to some subtype.
* Navigating generalization relationships from a subtype instance to
  its corresponding supertype instance.
* Subtype migration of one subtype into being instance of a different
  subtype.

=== Marking mechanics

The following is the suggested way to obtain and record the model metatdata
is:

* Start with a clean printout of the class diagram of the model on the
  largest size sheet of paper that can be conveniently obtained.
  Class diagrams for a cleanly presented model should be partitioned
  into smaller subsystems if the number of classes in the domain
  will not fit on readily available paper sizes.
  In practice, Letter size of A size paper is the most readily available
  and model drawings should take that into account.
* Read the action language or data flow diagrams of every processing
  activity in the model.
* While reading the model activities,
  annotate the class diagram with the information previously presented.
  For example,
  when action language statement reads an attribute, place an *R* next to the
  attribute's name.
  Similarly, attribute updates can be marked with a *U* or *W* character.
  The direction of relationship traversal can be annotated as an
  arrow pointing in the direction of the navigation and parallel to the
  relationship line on the class diagram.

The precise details of the notation used for the marking is not as important
as insuring that the previously mentioned information is gathered
and clearly indicated.
A project may choose to standarize the notation.
Do not hesitate to make notes on the diagram.
The results of this model marking analysis directly feeds the next steps in the
translation process.


// vim:syntax=asciidoc: