trunk/doc/howto-require.lyx

#LyX 2.1 created this file. For more info see http://www.lyx.org/
\lyxformat 474
\begin_document
\begin_header
\textclass book
\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_math auto
\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 a4paper
\use_geometry false
\use_package amsmath 2
\use_package amssymb 2
\use_package cancel 1
\use_package esint 0
\use_package mathdots 0
\use_package mathtools 1
\use_package mhchem 0
\use_package stackrel 1
\use_package stmaryrd 1
\use_package undertilde 1
\cite_engine basic
\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\justification true
\use_refstyle 0
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 2
\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 Chapter
Managing model definitions, libraries, and projects 
\begin_inset CommandInset label
LatexCommand label
name "cha:require"

\end_inset


\end_layout

\begin_layout Standard
Most complex models are built from parts in one or more libraries.
 In this chapter we show typical examples of how to make sure your model
 gets the libraries it needs.
 We then explain in more general terms the ASCEND mechanism which makes
 this work and how you can use it to manage multiple modeling projects simultane
ously.
\end_layout

\begin_layout Section
Using 
\family typewriter
REQUIRE
\family default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
REQUIRE
\end_layout

\end_inset

 and 
\family typewriter
PROVIDE
\family default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
PROVIDE
\end_layout

\end_inset


\end_layout

\begin_layout Subsection

\family typewriter
REQUIRE
\family default
ing 
\family typewriter
system.a4l
\family default

\begin_inset CommandInset label
LatexCommand label
name "ssec:require.requireSystem.a4l"

\end_inset


\end_layout

\begin_layout Standard
Suppose you are in a great hurry and want to create a simple model and solve
 it without concern for good style, dimensional consistency, or any of the
 other hobgoblins we preach about elsewhere.
 You will write equations using only generic_real variables as defined in
 
\family typewriter
system.a4l
\family default
.
 The equations in this example do not necessarily have a solution.
 In your ascdata (see howto1) directory you create an application model
 definition file 
\begin_inset Quotes eld
\end_inset


\family typewriter
myfile.a4c
\family default
" which looks like:
\end_layout

\begin_layout LyX-Code
REQUIRE "system.a4l";
\end_layout

\begin_layout LyX-Code
MODEL quick_n_dirty;
\end_layout

\begin_layout LyX-Code
x = y^2;
\end_layout

\begin_layout LyX-Code
y = x + 2*z;
\end_layout

\begin_layout LyX-Code
z = cos(x+y);
\end_layout

\begin_layout LyX-Code
x,y,z IS_A generic_real;
\end_layout

\begin_layout LyX-Code
(* homework problem 3, due May 21.
 *)
\end_layout

\begin_layout LyX-Code
END quick_n_dirty;
\end_layout

\begin_layout Standard
The very first line 
\family typewriter
REQUIRE "system.a4l";
\family default
 tells ASCEND to find and load a file named 
\family typewriter
system.a4l
\family default
 if it has not already been loaded or provided in some other way.
 This 
\family typewriter
REQUIRE
\family default
 statement must come before the 
\family typewriter
MODEL
\family default
 which uses the 
\family typewriter
generic_real
\family default
 ATOM that 
\family typewriter
system.a4l
\family default
 defines.
 
\end_layout

\begin_layout Standard
The 
\family typewriter
REQUIRE
\family default
 statements in a file should all come at the beginning of the file before
 any other text, including comments.
 This makes it very easy for other users or automated tools to determine
 which files, if any, your models require.
\end_layout

\begin_layout Standard
On the ASCEND command line (in the Console window or xterm) or in the Script
 window, you can then enter and execute the statement
\end_layout

\begin_layout LyX-Code
READ FILE "myfile.a4c";
\end_layout

\begin_layout Standard
to cause 
\family typewriter
system.a4l
\family default
 and then 
\family typewriter
myfile.a4c
\family default
 to be loaded.
\end_layout

\begin_layout Subsection
Chaining required files
\end_layout

\begin_layout Standard
Notice when you read 
\family typewriter
myfile.a4c
\family default
 that ASCEND prints messages about the files being loaded.
 You will see that a file 
\family typewriter
basemodel.a4l
\family default
 is also loaded.
 In 
\family typewriter
system.a4l
\family default
 you will find at the beginning the statements
\end_layout

\begin_layout Standard

\family typewriter
REQUIRE "basemodel.a4l";
\end_layout

\begin_layout Standard

\family typewriter
PROVIDE "system.a4l";
\end_layout

\begin_layout Standard
The basemodel library is loaded in turn because of the 
\family typewriter
REQUIRE
\family default
 statement in 
\family typewriter
system.a4l
\family default
.
 We will come back to what the 
\family typewriter
PROVIDE
\family default
 statement does in a moment.
 This chaining can be many files deep.
 To see a more complicated example, enter
\end_layout

\begin_layout LyX-Code

\family typewriter
READ FILE column.a4l;
\end_layout

\begin_layout Standard
and watch the long list of files that gets loaded.
 If you examine the first few lines of each file in the output list, you
 will see that each file REQUIRES only the next lower level of libraries.
 This style minimizes redundant loading messages and makes it easy to substitute
 equivalent libraries in the nested lower levels without editing too many
 higher level libraries.
 The term "equivalent libraries" is defined better in the later section
 on 
\family typewriter
PROVIDE
\family default
.
\end_layout

\begin_layout Subsection
Better application modeling practice
\end_layout

\begin_layout Standard
\begin_inset Marginal
status open

\begin_layout Plain Layout
never require system.a4l in an application model.
\end_layout

\end_inset

It is generally a bad idea to create a model using only 
\family typewriter
generic_real
\family default
 variables.
 The normal practice is to use correct units in equations and to use dimensional
 variables.
 In the following file we see that this is done by requiring 
\family typewriter
atoms.a4l
\family default
 instead of 
\family typewriter
system.a4l
\family default
 and by using correct units on the coefficients in the equations.
 
\end_layout

\begin_layout Standard

\family typewriter
REQUIRE "atoms.a4l"; MODEL quick_n_clean;
\end_layout

\begin_layout Standard

\family typewriter
x = y^2/1{PI*radian};
\end_layout

\begin_layout Standard

\family typewriter
y = x + 2{PI*radian}*z;
\end_layout

\begin_layout Standard

\family typewriter
z = cos(x+y);
\end_layout

\begin_layout Standard

\family typewriter
x, y IS_A angle;
\end_layout

\begin_layout Standard

\family typewriter
z IS_A dimensionless;
\end_layout

\begin_layout Standard

\family typewriter
(* homework problem 3, due May 21.
 *)
\end_layout

\begin_layout Standard

\family typewriter
END quick_n_clean;
\end_layout

\begin_layout Subsection
Substitute libraries
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
substitute libraries
\end_layout

\end_inset

 and 
\family typewriter
PROVIDE
\family default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
PROVIDE
\end_layout

\end_inset


\end_layout

\begin_layout Standard
ASCEND keeps a list of the already loaded files, as we hinted at in Section
 
\begin_inset CommandInset ref
LatexCommand ref
reference "ssec:require.requireSystem.a4l"

\end_inset


\noun off
.
 A library file should contain a 
\family typewriter
\noun default
PROVIDE
\family default
\noun off
 statement, as 
\family typewriter
\noun default
system.a4l
\family default
\noun off
 does, telling what library it supplies.
 Normally the 
\family typewriter
\noun default
PROVIDE
\family default
\noun off
 statement just repeats the file name, but this is not always the case.
 For example, see the first few lines of the file 
\family typewriter
\noun default
ivpsystem.a4l
\family default
\noun off
, which include the statement
\end_layout

\begin_layout LyX-Code
PROVIDE "system.a4l";
\end_layout

\begin_layout Standard
indicating that 
\family typewriter
ivpsystem.a4l
\family default
 is intended to be equivalent to file 
\family typewriter
system.a4l
\family default
 while also supplying new features.
 When ivpsystem.a4l is loaded both "
\family typewriter
system.a4l
\family default
" and "
\family typewriter
ivpsystem.a4l
\family default
" get added to the list of already loaded files.
 For one explanation of when this behavior might be desirable, see Section
 
\begin_inset CommandInset ref
LatexCommand vref
reference "ssec:require.requireSystem.a4l"

\end_inset


\noun off
.
 Another use for this behavior is when creating and testing a second library
 to eventually replace the first one.
\end_layout

\begin_layout Standard
When a second library provides compatible but extended definitions similar
 to a first library, the second can be substituted for the first one.
 The second library will obviously have a different file name, but there
 is no need to load the first library if we already have the second one
 loaded.
 
\family typewriter
ivpsystem.a4l
\family default
 is a second library substitutable for the first library 
\family typewriter
system.a4l
\family default
.
 Note that the reverse is not true: 
\family typewriter
system.a4l
\family default
 does not 
\end_layout

\begin_layout LyX-Code
PROVIDE "ivpsystem.a4l"; 
\end_layout

\begin_layout Standard
so system is not a valid substitute for ivpsystem.
 
\end_layout

\begin_layout Subsection

\family typewriter
REQUIRE
\family default
 and combining modeling packages
\begin_inset CommandInset label
LatexCommand label
name "ssec:require.requireCombiningPackages"

\end_inset


\end_layout

\begin_layout Standard
Model libraries frequently come in interrelated groups.
 For example, the models referred to in Ben Allan's thesis are published
 electronically as a package models/ben/ in ASCEND IV release 0.9.
 To use Ben's distillation libraries, which require rather less memory than
 the current set of more flexible models, your application model should
 have the statement
\end_layout

\begin_layout LyX-Code
REQUIRE "ben/bencolumn.a4l";
\end_layout

\begin_layout Standard
at the beginning.
\end_layout

\begin_layout Standard
Combining models from different packages may be tricky if the package authors
 have not documented them well.
 Since all packages are open source code that you can copy into your ascdata
 directory and modify to suit your needs, the process of combining libraries
 usually amounts to changing the names of the conflicting model definitions
 in your copy.
 
\end_layout

\begin_layout Standard
Do NOT use 
\backslash
 instead of / in the package name given to a 
\family typewriter
REQUIRE
\family default
 statement even if you are forced to use Microsoft Windows.
 
\end_layout

\begin_layout Section
How 
\family typewriter
REQUIRE
\family default
 finds the files it loads
\end_layout

\begin_layout Standard
The file loading mechanism of 
\family typewriter
REQUIRE
\family default
 makes it simple to manage several independent sets of models in simultaneous
 development.
 We must explain this mechanism or the model management may seem somewhat
 confusing.
 When a statement is processed, ASCEND checks in a number of locations for
 a file with that name: ascdata, the current directory, and the 
\family typewriter
ascend4/models
\family default
 directory.
 We will describe how you can extend this list later.
 ASCEND also looks for model packages in each of these same locations.
 
\end_layout

\begin_layout Subsection
ascdata
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ascdata
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If your 
\family typewriter
ascdata
\family default
 directory exists and is readable, ASCEND looks there first for required
 files.
 Thus you can copy one of our standard libraries from the directory 
\family typewriter
ascend4/models
\family default
 to your 
\family typewriter
ascdata
\family default
 directory and modify it as you like.
 Your modification will be loaded instead of our standard library.
 The 
\family typewriter
ascdata
\family default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ascdata
\end_layout

\end_inset

 directory is typically put into your HOME
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
HOME
\end_layout

\end_inset

 directory (see Section
\begin_inset space ~
\end_inset


\begin_inset CommandInset ref
LatexCommand vref
reference "ssec:atoms.newVarType"

\end_inset

).
\end_layout

\begin_layout Subsection
the current directory
\begin_inset CommandInset label
LatexCommand label
name "ssec:require.currentDir"

\end_inset


\end_layout

\begin_layout Standard
The current directory is what you get if you type 'pwd' at the ASCEND Console
 or xterm prompt.
 Under Microsoft Windows, the current directory is usually some useless
 location.
 Under UNIX, the current directory is usually the directory from which you
 started ASCEND.
\end_layout

\begin_layout Subsection
ascend4/models/
\end_layout

\begin_layout Standard
The standard (CMU) models and packages distributed with ASCEND are found
 in the 
\family typewriter
ascend4/models/
\family default
 subdirectory where ASCEND is installed.
 This directory sits next to the directory 
\family typewriter
ascend4/bin/
\family default
 where the 
\family typewriter
ascend4
\family default
 or 
\family typewriter
ascend4.exe
\family default
 executable is located.
\end_layout

\begin_layout Subsection
Multiple modeling projects
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
multiple modeling projects
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you dislike navigating multi-level directories while working on a single
 modeling project, you can separate projects by keeping all files related
 to your current project in one directory and changing to that directory
 before starting ASCEND.
 If you have files that are required in all your projects, keep those files
 in your 
\family typewriter
ascdata
\family default
 directory.
 Under Windows, 
\family typewriter
cd
\family default
 to the directory containing the current project from the Console window
 after starting ASCEND.
\end_layout

\begin_layout Subsection
Example: Finding 
\family typewriter
ben/bencolumn.a4l
\family default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
bencolumn.a4l
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Suppose an application model requires 
\family typewriter
bencolumn.a4l
\family default
 from package 
\family typewriter
ben
\family default
 as shown in Section 
\begin_inset CommandInset ref
LatexCommand ref
reference "ssec:require.requireCombiningPackages"

\end_inset


\noun off
.
 Normally ASCEND will execute this statement by searching for:
\end_layout

\begin_layout LyX-Code
~/ascdata/ben/bencolumn.a4l
\end_layout

\begin_layout LyX-Code
./ben/bencolumn.a4l
\end_layout

\begin_layout LyX-Code
$ASCENDDIST/ascend4/models/ben/bencolumn.a4l
\end_layout

\begin_layout Standard
Assuming we started ASCEND from directory 
\family typewriter
/usr1/ballan/projects/test1
\family default
 under UNIX, the full names of these might be
\end_layout

\begin_layout LyX-Code
/usr0/ballan/ascdata/ben/bencolumn.a4l
\end_layout

\begin_layout LyX-Code
/usr1/ballan/projects/test1/ben/bencolumn.a4l
\end_layout

\begin_layout LyX-Code
/usr/local/lib/ascend4/models/ben/bencolumn.a4l
\end_layout

\begin_layout Standard
Assuming we started ASCEND from some shortcut on a Windows desktop, the
 full names of these locations might be
\end_layout

\begin_layout LyX-Code
C:
\backslash
winnt
\backslash
profiles
\backslash
ballan
\backslash
ascdata
\backslash
ben
\backslash
bencolumn.a4l 
\end_layout

\begin_layout LyX-Code
C:
\backslash
Program Files
\backslash
netscape
\backslash
ben
\backslash
bencolumn.a4l 
\end_layout

\begin_layout LyX-Code
C:
\backslash
ASCEND
\backslash
ascend4
\backslash
models
\backslash
ben
\backslash
bencolumn.a4l
\end_layout

\begin_layout Standard
The first of these three which actually exists on your disk will be the
 file that is loaded.
\end_layout

\begin_layout Subsection
How 
\family typewriter
REQUIRE
\family default
 handles file and definition conflicts
\begin_inset CommandInset label
LatexCommand label
name "ssec:require.handleConflicts"

\end_inset


\end_layout

\begin_layout Standard
Normally you simply delete all types before loading a new or revised set
 of ASCEND models and thus you avoid most conflicts.
 When you are working with a large simulation and several smaller ones,
 you may not want to delete all the types, however.
 We decided to make 
\family typewriter
REQUIRE
\family default
 handle this situation and the almost inevitable redundant 
\family typewriter
REQUIRE
\family default
 statements that occur in the following reasonable way.
\end_layout

\begin_layout Standard
When a file is 
\family typewriter
REQUIRE
\family default
d, ASCEND first checks the list of loaded and provided files for a name
 that matches.
 If the name is found, then that file is checked to see if it has changed
 since it was loaded.
 If the file has changed, then any definition that was changed is loaded
 in the ASCEND Library and the new definition is used in building any subsequent
ly compiled simulations.
 Old simulations remain undisturbed and are not updated to use the new definitio
ns since there may be conflicts that cannot be automatically resolved.
\end_layout

\begin_layout Subsection
Extending the list of searched directories
\end_layout

\begin_layout Standard
ASCEND uses the environment variable
\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
environment variable
\end_layout

\end_inset

 
\family typewriter
ASCENDLIBRARY
\family default

\begin_inset Index idx
status collapsed

\begin_layout Plain Layout
ASCENDLIBRARY
\end_layout

\end_inset

 as the list of directory paths to search for required files.
 Normally you do not set this environment variable, and ASCEND works as
 described above.
 
\end_layout

\begin_layout Standard
To see or change the value of 
\family typewriter
ASCENDLIBRARY
\family default
 that ASCEND is using, examine 
\family typewriter
ASCENDLIBRARY
\family default
 in the System utilities window available from the Script Tools menu.
 Changes made to environment variables in the utilities window are NOT saved.
 If you are clever enough to set environment variables before running ASCEND,
 you can make it look anywhere you want to put your model files.
 Consult your operating system guru for information on setting environment
 variables if you do not already know how.
\end_layout

\begin_layout Standard

\end_layout

\end_body
\end_document