/[ascend]/trunk/doc/howto-units.lyx
ViewVC logotype

Contents of /trunk/doc/howto-units.lyx

Parent Directory Parent Directory | Revision Log Revision Log


Revision 825 - (show annotations) (download) (as text)
Mon Aug 21 23:41:31 2006 UTC (18 years, 3 months ago) by johnpye
Original Path: trunk/doc/lyxFinal/howto-units.lyx
File MIME type: application/x-lyx
File size: 15770 byte(s)
Copying documentation into code tree
1 #LyX 1.4.1 created this file. For more info see http://www.lyx.org/
2 \lyxformat 245
3 \begin_document
4 \begin_header
5 \textclass book
6 \language english
7 \inputencoding auto
8 \fontscheme default
9 \graphics default
10 \paperfontsize default
11 \spacing single
12 \papersize default
13 \use_geometry false
14 \use_amsmath 2
15 \cite_engine basic
16 \use_bibtopic false
17 \paperorientation portrait
18 \secnumdepth 3
19 \tocdepth 3
20 \paragraph_separation indent
21 \defskip medskip
22 \quotes_language english
23 \papercolumns 1
24 \papersides 1
25 \paperpagestyle default
26 \tracking_changes false
27 \output_changes true
28 \end_header
29
30 \begin_body
31
32 \begin_layout Chapter
33 Defining New Units of Measure
34 \begin_inset LatexCommand \label{cha:units}
35
36 \end_inset
37
38
39 \end_layout
40
41 \begin_layout Standard
42 Occasionally units of measure are needed that do not come predefined in
43 the ASCEND system.
44 You can define a new unit of measure by defining the conversion factor.
45 In this chapter, we examine how to do this easily for an individual user
46 and on a system-wide basis.
47
48 \end_layout
49
50 \begin_layout Section
51
52 \emph on
53 Caveats
54 \end_layout
55
56 \begin_layout Standard
57 \begin_inset Marginal
58 status collapsed
59
60 \begin_layout Standard
61 Order matters!
62 \end_layout
63
64 \end_inset
65
66 Order matters for defining units of measure in three ways.
67 \end_layout
68
69 \begin_layout Itemize
70 a unit of measure must be defined before it is used anywhere.
71 \end_layout
72
73 \begin_layout Itemize
74 the first definition ASCEND reads for a unit of measure is the only definition
75 ASCEND sees.
76 \end_layout
77
78 \begin_layout Itemize
79 new units can be defined only from already defined units.
80 \end_layout
81
82 \begin_layout Standard
83 Measuring units are absolutely global in the ASCEND environment -- they
84 are not deleted when the Library of types is deleted.
85 Once you define a unit's conversion factor, you are stuck with it until
86 you shut down and restart ASCEND.
87 For any unit conversion definition, only the first conversion factor seen
88 is accepted.
89 Redefinitions of the same unit are ignored.
90 \end_layout
91
92 \begin_layout Standard
93 \begin_inset Marginal
94 status collapsed
95
96 \begin_layout Standard
97 Multiplicative unit conversions only!
98 \end_layout
99
100 \end_inset
101
102 The various units ASCEND uses are all obtained by conversion factors (multiplica
103 tion only) from the SI units.
104 So, for example, temperatures may be in degrees Rankine but not in Fahrenheit.
105 In this chapter we address creating new conversion factors.
106 For handling non-
107 \end_layout
108
109 \begin_layout Standard
110 multiplicative conversions (such as the Fahrenheit or Celsius offsets) see
111 Section\InsetSpace ~
112
113 \begin_inset LatexCommand \vref{sec:dimeqns.Fahrenheit}
114
115 \end_inset
116
117 .
118 \end_layout
119
120 \begin_layout Section
121 Individualised units
122 \end_layout
123
124 \begin_layout Standard
125 There are two scenarios for individualized units of measure.
126 One in which you need a measure defined only for a specific model and another
127 in which you want to define a measure that you will use throughout your
128 modeling activities in the future.
129 The syntax for both is the same, but where best to put the UNITS statement
130 differs.
131 \end_layout
132
133 \begin_layout Subsection
134 Units of measure for a specific model
135 \end_layout
136
137 \begin_layout Standard
138 Units of measure that are used in only one model can be defined at the beginning
139 of the model itself or before the model, but not the units appear in the
140 model definition.
141 Let us suppose you want to measure speed in {furlong/fortnight} in a model.
142 ASCEND does not define
143 \family typewriter
144 furlong
145 \family default
146 ,
147 \family typewriter
148 fortnight
149 \family default
150 , or
151 \family typewriter
152 furlong/fortnight
153 \family default
154 .
155 (Interestingly, we have been unable to find standard definitions for them!).
156 \end_layout
157
158 \begin_layout LyX-Code
159 MODEL mock_turtle;
160 \end_layout
161
162 \begin_layout LyX-Code
163 d IS_A distance;
164 \end_layout
165
166 \begin_layout LyX-Code
167 delta_t IS_A time;
168 \end_layout
169
170 \begin_layout LyX-Code
171 s IS_A speed
172 \end_layout
173
174 \begin_layout LyX-Code
175
176 \end_layout
177
178 \begin_layout LyX-Code
179 s = d/delta_t;
180 \end_layout
181
182 \begin_layout LyX-Code
183 (* We really should write s * delta_t = d;
184 \end_layout
185
186 \begin_layout LyX-Code
187 to avoid division by zero.
188 *)
189 \end_layout
190
191 \begin_layout LyX-Code
192
193 \end_layout
194
195 \begin_layout LyX-Code
196 UNITS
197 \end_layout
198
199 \begin_layout LyX-Code
200 furlong = {3.17*kilometer};
201 \end_layout
202
203 \begin_layout LyX-Code
204 fortnight = {10*day};
205 \end_layout
206
207 \begin_layout LyX-Code
208 END UNITS;
209 \end_layout
210
211 \begin_layout LyX-Code
212
213 \end_layout
214
215 \begin_layout LyX-Code
216 METHODS
217 \end_layout
218
219 \begin_layout LyX-Code
220 METHOD default_self;
221 \end_layout
222
223 \begin_layout LyX-Code
224 d := 1 {furlong};
225 \end_layout
226
227 \begin_layout LyX-Code
228 t := 5 {hours};
229 \end_layout
230
231 \begin_layout LyX-Code
232 END default_self;
233 \end_layout
234
235 \begin_layout LyX-Code
236
237 \end_layout
238
239 \begin_layout LyX-Code
240 (* other standard methods omitted *)
241 \end_layout
242
243 \begin_layout LyX-Code
244
245 \end_layout
246
247 \begin_layout LyX-Code
248 END mock_turtle;
249 \end_layout
250
251 \begin_layout Standard
252 In mock_turtle we define
253 \family typewriter
254 furlong
255 \family default
256 and
257 \family typewriter
258 fortnight
259 \family default
260 conversions
261 \series bold
262 before
263 \series default
264 they are used in the methods and before any equations which use them.
265 Also, notice that, even though ASCEND rejects this model
266 \family typewriter
267 mock_turtle
268 \family default
269 , as it will because of the missing "
270 \family typewriter
271 ;
272 \family default
273 " after "speed" in the fourth line,
274 \family typewriter
275 furlong
276 \family default
277 and
278 \family typewriter
279 fortnight
280 \family default
281 still get defined.
282 The
283 \family typewriter
284 UNITS
285 \family default
286 statement can appear in any context and gets processed regardless of any
287 other errors in that context.
288 \end_layout
289
290 \begin_layout Subsection
291 UNITS OF MEASURE FOR ALL YOUR PERSONAL MODELS
292 \end_layout
293
294 \begin_layout Standard
295 If you commonly use a set of units that is not in the default ASCEND library
296
297 \family typewriter
298 measures.a4l
299 \family default
300 , you can create your own personal library of units in the user data directory
301
302 \family typewriter
303 ascdata
304 \family default
305 .
306 The location of this directory is given by ASCEND at the end of all the
307 start-up spew it prints to the Console window (or xterm under UNIX) as
308 shown below.
309 You will see a path other than
310 \family typewriter
311 /usr0/ballan/
312 \family default
313 of course.
314 \end_layout
315
316 \begin_layout LyX-Code
317 -----------------------------------
318 \end_layout
319
320 \begin_layout LyX-Code
321 User data directory is /usr0/ballan/ascdata
322 \end_layout
323
324 \begin_layout LyX-Code
325 -----------------------------------
326 \end_layout
327
328 \begin_layout Standard
329 Create the library file
330 \family typewriter
331 myunits.a4l
332 \family default
333 in your
334 \family typewriter
335 ascdata
336 \family default
337 directory.
338 This file should contain a
339 \family typewriter
340 UNITS
341 \family default
342 statement and any comments or
343 \family typewriter
344 NOTES
345 \family default
346 you wish to make.
347 This file should contain any conversions that you change often.
348 For example:
349 \end_layout
350
351 \begin_layout LyX-Code
352 UNITS
353 \end_layout
354
355 \begin_layout LyX-Code
356 (* Units for Norway, maybe?*)
357 \end_layout
358
359 \begin_layout LyX-Code
360 euro = {1*currency};
361 \end_layout
362
363 \begin_layout LyX-Code
364 (* currency is the fundamental financial unit *)
365 \end_layout
366
367 \begin_layout LyX-Code
368 kroner = {0.00314*euro};
369 \end_layout
370
371 \begin_layout LyX-Code
372 nk = {kroner};
373 \end_layout
374
375 \begin_layout LyX-Code
376 USdollar = {0.9*euro};
377 \end_layout
378
379 \begin_layout LyX-Code
380 CANdollar = {0.65*USdollar};
381 \end_layout
382
383 \begin_layout LyX-Code
384 END UNITS;
385 \end_layout
386
387 \begin_layout Standard
388 Note that this file contains a definition of
389 \family typewriter
390 USdollar
391 \family default
392 different from that given in the standard library
393 \family typewriter
394 measures.a4l
395 \family default
396 .
397 ASCEND will warn you about the conflict.
398 You must load
399 \family typewriter
400 myunits.a4l
401 \family default
402 into ASCEND before
403 \family typewriter
404 atoms.a4l
405 \family default
406 or any of our higher level libraries.
407 You can ensure that this happens by putting the statement
408 \end_layout
409
410 \begin_layout LyX-Code
411 REQUIRE "myunits.a4l";
412 \end_layout
413
414 \begin_layout Standard
415 on the very first line in all your model definition files.
416 \end_layout
417
418 \begin_layout Section
419 NEW SYSTEM-WIDE UNITS
420 \end_layout
421
422 \begin_layout Standard
423 Suppose you are maintaining ASCEND on a network of computers with many users.
424 You have a standard set of models stored in a centrally located directory,
425 and you want to define units for use by everyone on the network.
426 In this case, just edit
427 \family typewriter
428 models/measures.a4l
429 \family default
430 , the default units of measure library.
431 ASCEND is an open system.
432
433 \end_layout
434
435 \begin_layout Standard
436 Make the new unit conversion definition statement(s) of the form
437 \end_layout
438
439 \begin_layout LyX-Code
440 newunit = {combination of old units};
441 \end_layout
442
443 \begin_layout Standard
444 as described in **Section 9.2.** In the file
445 \family typewriter
446 measures.a4l
447 \family default
448 , add your statement(s) anywhere inside the block of definitions that starts
449 with
450 \family typewriter
451 UNITS
452 \family default
453 and ends with
454 \family typewriter
455 END UNITS
456 \family default
457 .
458 The existing definitions are divided up into groups by comment statements.
459 If your conversion belongs to one of the groups, it is best to put the
460 conversion in that group.
461 The groups are given in Table
462 \begin_inset LatexCommand \ref{tab:units.groupOfUnits}
463
464 \end_inset
465
466 .
467 \end_layout
468
469 \begin_layout Standard
470 \begin_inset Float table
471 wide false
472 sideways false
473 status open
474
475 \begin_layout Caption
476 Groups of units in the current measures library
477 \begin_inset LatexCommand \label{tab:units.groupOfUnits}
478
479 \end_inset
480
481
482 \end_layout
483
484 \begin_layout Standard
485 \begin_inset Tabular
486 <lyxtabular version="3" rows="21" columns="1">
487 <features>
488 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
489 <row topline="true" bottomline="true">
490 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
491 \begin_inset Text
492
493 \begin_layout Standard
494
495 \family typewriter
496 distance
497 \end_layout
498
499 \end_inset
500 </cell>
501 </row>
502 <row topline="true">
503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
504 \begin_inset Text
505
506 \begin_layout Standard
507
508 \family typewriter
509 mass
510 \end_layout
511
512 \end_inset
513 </cell>
514 </row>
515 <row topline="true">
516 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
517 \begin_inset Text
518
519 \begin_layout Standard
520
521 \family typewriter
522 time
523 \end_layout
524
525 \end_inset
526 </cell>
527 </row>
528 <row topline="true" endhead="true">
529 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
530 \begin_inset Text
531
532 \begin_layout Standard
533
534 \family typewriter
535 molecular quantities
536 \end_layout
537
538 \end_inset
539 </cell>
540 </row>
541 <row topline="true" endhead="true">
542 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
543 \begin_inset Text
544
545 \begin_layout Standard
546
547 \family typewriter
548 money
549 \end_layout
550
551 \end_inset
552 </cell>
553 </row>
554 <row topline="true" endhead="true">
555 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
556 \begin_inset Text
557
558 \begin_layout Standard
559
560 \family typewriter
561 reciprocal time (frequency)
562 \end_layout
563
564 \end_inset
565 </cell>
566 </row>
567 <row topline="true" endhead="true">
568 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
569 \begin_inset Text
570
571 \begin_layout Standard
572
573 \family typewriter
574 area
575 \end_layout
576
577 \end_inset
578 </cell>
579 </row>
580 <row topline="true" endhead="true">
581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
582 \begin_inset Text
583
584 \begin_layout Standard
585
586 \family typewriter
587 volume
588 \end_layout
589
590 \end_inset
591 </cell>
592 </row>
593 <row topline="true" endhead="true">
594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
595 \begin_inset Text
596
597 \begin_layout Standard
598
599 \family typewriter
600 force
601 \end_layout
602
603 \end_inset
604 </cell>
605 </row>
606 <row topline="true" endhead="true">
607 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
608 \begin_inset Text
609
610 \begin_layout Standard
611
612 \family typewriter
613 pressure
614 \end_layout
615
616 \end_inset
617 </cell>
618 </row>
619 <row topline="true" endhead="true">
620 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
621 \begin_inset Text
622
623 \begin_layout Standard
624
625 \family typewriter
626 energy
627 \end_layout
628
629 \end_inset
630 </cell>
631 </row>
632 <row topline="true" endhead="true">
633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
634 \begin_inset Text
635
636 \begin_layout Standard
637
638 \family typewriter
639 power
640 \end_layout
641
642 \end_inset
643 </cell>
644 </row>
645 <row topline="true" endhead="true">
646 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
647 \begin_inset Text
648
649 \begin_layout Standard
650
651 \family typewriter
652 absolute viscosity
653 \end_layout
654
655 \end_inset
656 </cell>
657 </row>
658 <row topline="true" endhead="true">
659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
660 \begin_inset Text
661
662 \begin_layout Standard
663
664 \family typewriter
665 electric charge
666 \end_layout
667
668 \end_inset
669 </cell>
670 </row>
671 <row topline="true" bottomline="true">
672 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
673 \begin_inset Text
674
675 \begin_layout Standard
676
677 \family typewriter
678 miscellaneous electromagnetic
679 \end_layout
680
681 \end_inset
682 </cell>
683 </row>
684 <row topline="true" bottomline="true">
685 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
686 \begin_inset Text
687
688 \begin_layout Standard
689
690 \family typewriter
691 swiped from C math.h
692 \end_layout
693
694 \end_inset
695 </cell>
696 </row>
697 <row topline="true" bottomline="true">
698 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
699 \begin_inset Text
700
701 \begin_layout Standard
702
703 \family typewriter
704 constant based conversions
705 \end_layout
706
707 \end_inset
708 </cell>
709 </row>
710 <row topline="true" bottomline="true">
711 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
712 \begin_inset Text
713
714 \begin_layout Standard
715
716 \family typewriter
717 subtly dimensionless measures
718 \end_layout
719
720 \end_inset
721 </cell>
722 </row>
723 <row topline="true" bottomline="true">
724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
725 \begin_inset Text
726
727 \begin_layout Standard
728
729 \family typewriter
730 light quantities
731 \end_layout
732
733 \end_inset
734 </cell>
735 </row>
736 <row topline="true" bottomline="true">
737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
738 \begin_inset Text
739
740 \begin_layout Standard
741
742 \family typewriter
743 miscellaneous rates
744 \end_layout
745
746 \end_inset
747 </cell>
748 </row>
749 <row topline="true" bottomline="true">
750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
751 \begin_inset Text
752
753 \begin_layout Standard
754
755 \family typewriter
756 time variant conversions
757 \end_layout
758
759 \end_inset
760 </cell>
761 </row>
762 </lyxtabular>
763
764 \end_inset
765
766
767 \end_layout
768
769 \end_inset
770
771
772 \end_layout
773
774 \begin_layout Section
775 Send them in
776 \end_layout
777
778 \begin_layout Standard
779 We are always on the lookout for useful unit conversions to add to
780 \family typewriter
781 measures.a4l
782 \family default
783 .
784 If you create a
785 \family typewriter
786 myunits.a4l
787 \family default
788 containing unit conversion definitions of general use (i.e.
789 not currency exchange rates and other time-varying conversions), please
790 mail us a copy and include your name in a comment.
791 Thank you very much.
792 \end_layout
793
794 \end_body
795 \end_document

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22