scilab/modules/scicos/src/modelica_compiler/README.txt

   1 1. Introduction
   2 ===============
   3
   4 This document describes the Modelica compiler Modelicac.
   5 Modelicac is a tool that compiles a subset of the Modelica 2.0 language (see
   6 section 4). This subset allows the description of continuous-time physical
   7 models that can be simulated under AMESim.
   8
   9
  10 2. How to compile Modelicac
  11 ===========================
  12
  13 Be sure to have a recent Objective Caml (v.3.06 or later) properly installed
  14 on the machine.
  15 In the source directory, type:
  16
  17   make depend
  18
  19 then:
  20
  21   make (to compile a bytecode version of Modelicac)
  22 or:
  23   make opt (to compile a native-code version of Modelicac)
  24
  25 Ocaml code HTML documentation can be automatically generated from module types
  26 by typing:
  27
  28  make doc
  29
  30 This will create a directory named "doc" in the current directory. "index.html"
  31 is the entry point of the documentation.
  32
  33
  34 3. How to use Modelicac
  35 =======================
  36
  37 Modelicac compiles Modelica files whose name ends by ".mo".
  38 The modelicac command, when invoked with the appropriate options, may produce:
  39 - A C file containing a function suitable to be called by AMESim in
  40   order to perform a model simulation;
  41 - A "*.moc" file which is the format of a precompiled Modelica class stored for
  42   later instantiation.
  43
  44 It is required that each "*.mo" file contains exactly one Modelica class
  45 (see section 4) and that the name of the class matches the name of the file that
  46 contains its definition.
  47
  48 By default, Modelicac removes every variable that is not reinitialized in a
  49 "when" section and for which it can express its value with respect to the
  50 remaining variables of the system. It is possible to disable this option by
  51 specifying "-keep-all-variables" when calling Modelicac (see below).
  52
  53 Usage
  54 -----
  55
  56 modelicac [-c] [-o <outputfile>] <inputfile> [other options]
  57
  58 -c: Compile only, do not instantiate. Modelicac produces a "*.moc" file when
  59     invoked with that option.
  60 -o <outputfile>: Set output file name to <outputfile> (this option also works
  61                  with -c option but is somewhat useless because of the class
  62                  name restrictions given above).
  63 Other options include:
  64 -L <directory>: Add <directory> to the list of directories to be searched when
  65                 producing a C file (no effect when used with -c).
  66 -hpath <directory>: Specify a path to be added to #include directives in the
  67                     generated C code.
  68 -keep-all-variables: Do not remove any variable from the initial system.
  69 -jac: Generate analytic jacobian matrix code.
  70 -no-parameter-removal: Do not remove any parameter
  71 -no-simplifs: Same as -keep-all-variables -no-parameter-removal
  72 -xml: Generate an XML version of the model instead of target code
  73 -with-init-in <filename>: Generate code for 'separate initialization' mode
  74                           (where initialization data is loaded from
  75                           <filename>)
  76 -with-init-out <filename>: Generate code for 'separate initialization' mode
  77                            (where initialization data is saved in
  78                            <filename>)
  79
  80 Examples
  81 -------
  82
  83 +------------------------------------------------------------------------------+
  84 | Modelicac invokation         | Result                                        |
  85 +------------------------------+-----------------------------------------------+
  86 | modelicac foo.mo             | Produces a file named "foo.c" containing a    |
  87 |                              | C function named "foo" to be called by AMESim.|
  88 +------------------------------+-----------------------------------------------+
  89 | modelicac -c foo.mo          | Produces a file named "foo.moc" containing a  |
  90 |                              | precompiled class named "foo".                |
  91 +------------------------------+-----------------------------------------------+
  92 | modelicac -o dir/bar.c       | Same as "modelicac foo.mo", but output file   |
  93 |  foo.mo                      | name is "bar.c" and the resulting file is     |
  94 |                              | located in directory "dir".                   |
  95 +------------------------------+-----------------------------------------------+
  96 | modelicac -L dir1 -L dir2 ...| Same as "modelicac foo.mo", but if some       |
  97 | -L dirN foo.mo               | precompiled class "bar" needed by class "foo" |
  98 |                              | isn't found in the current directory (i.e.    |
  99 |                              | there is no file named "bar.moc" in the       |
 100 |                              | current directory), it is searched into       |
 101 |                              | "dir1", and, if not found, into "dir2", ...,  |
 102 |                              | "dirN" until a file named "bar.moc" is found. |
 103 +------------------------------+-----------------------------------------------+
 104
 105
 106 3. The compiled Modelica subset
 107 ===============================
 108
 109  The Modelicac compiler compiles a subset of the Modelica language that allows
 110 the description of some countinuous equational models. Each Modelica class is
 111 stored in its own file whose name is the name of the class followed by the "mo"
 112 extension.
 113
 114 Restrictions on the declaration of a modelica class header
 115 ----------------------------------------------------------
 116  - only the keyword "class" is allowed to declare a Modelica class ("function"
 117    is allowed to define functions, but in a very restrictive way, see below);
 118  - "within" is not allowed ;
 119  - a class cannot be "final" ;
 120  - short class definitions (type declarations) are not allowed ;
 121  - inheritance is not allowed ;
 122  - "encapsulated" and "partial" classes are not allowed ;
 123
 124 Restrictions on the declaration of the components of a class
 125 ------------------------------------------------------------
 126  - imports are not allowed ;
 127  - inner classes are not allowed ;
 128  - "inner", "outer" are not allowed ;
 129  - "protected" component lists are not allowed ;
 130  - "final" and "replaceable" are not allowed ;
 131  - "external" is restricted (see "Restrictions on external function
 132    definitions") ;
 133  - "constant" is not allowed ;
 134  - "input" and "output" may only be used to define I/O ports of the toplevel
 135    class beeing compiled to C code (see example below) ;
 136  - "algorithm" sections are not allowed ;
 137  - arrays must contain numerical types.
 138
 139 Restrictions on modifications
 140 -----------------------------
 141  - modifications may only apply to base types, scalar or not ;
 142  - selections of subarrays are not allowed (i.e. a[:].b = ...) ;
 143  - "redeclare", "each" and "final" are not allowed.
 144
 145 Restrictions on equations
 146 -------------------------
 147  - equational "if" is not allowed in the specification of an equation.
 148
 149 Restrictions on expressions
 150 -----------------------------
 151  - "for" expressions must have an integer range (since algorithms are not
 152    allowed) ;
 153  - selection of subarrays is restricted to numerical arrays ;
 154  - array concatenation (using "[" and "]") is not allowed.
 155
 156 Restrictions on external function definitions
 157 ---------------------------------------------
 158  Only functions taking zero or more Integer scalars, String scalars,
 159 Real scalars or Real arrays and returning exactly one
 160 Real scalar are supported.
 161  External functions must be declared in the Modelica file that
 162 contains models that use them.
 163 The compiler assumes a corresponding C function with the same
 164 name to be provided by the simulation environment. For example:
 165
 166 function Blackbox
 167   input Real u[:];
 168   output Real y;
 169 external;
 170 end Blackbox;
 171
 172  This function can be called from a Modelica model using the following
 173 syntax:
 174
 175 ...Blackbox(u)...
 176
 177  The corresponding C function is declared with the following signature:
 178
 179 double blackbox(double *, int );
 180
 181 (the last argument will be the size of the array whose first element
 182 is pointed to by the first argument, as specified in the Modelica
 183 Language Specification)