# Diff of /trunk/doc/user/escript.tex

revision 2645 by jfenwick, Mon Jul 20 06:20:06 2009 UTC revision 2646 by jfenwick, Fri Sep 4 00:13:00 2009 UTC
# Line 1097  returns a function which is $1$ where \v Line 1097  returns a function which is $1$ where \v
1097  returns a function which is $1$ where \var{a} different from zero with tolerance \var{tol} and $0$ otherwise. If \var{tol} is not present, the absolute maximum value of C{a} times C{rtol} is used.  returns a function which is $1$ where \var{a} different from zero with tolerance \var{tol} and $0$ otherwise. If \var{tol} is not present, the absolute maximum value of C{a} times C{rtol} is used.
1098  \end{funcdesc}  \end{funcdesc}
1099
1100    \subsection{Interpolating Data}
1101    \index{interpolateTable}
1102    In some cases, it may be useful to produce Data objects which fit some user defined function.
1103    Manually modifying each value in the Data object is not a good idea since it depends on
1104    knowing the location and order of each datapoint in the domain.
1105    Instead \escript can use an interpolation table to produce a Data object.
1106
1107    The following example is available as int_save.py in the examples directory.
1108    We will produce a \Data object which aproximates a sine curve.
1109
1110    \begin{python}
1111    from esys.escript import saveDataCSV, sup
1112    import numpy
1113    from esys.finley import Rectangle
1114
1115    n=4
1116    r=Rectangle(n,n)
1117    x=r.getX()
1118    x0=x[0]
1119    x1=x[1]    #we'll use this later
1120    toobig=100
1121    \end{python}
1122
1123    First we produce an interpolation table.
1124    \begin{python}
1125    sine_table=[0, 0.70710678118654746, 1, 0.70710678118654746, 0,
1126               -0.70710678118654746, -1, -0.70710678118654746, 0,
1127                0.70710678118654746]
1128    \end{python}
1129
1130    We wish to identify $0$ and $1$ with the ends of the curve.
1131    That is, with the first and eighth values in the table.
1132    But \var{x0} contains values between $0$ and $1$ inclusive so we need to continue the table to the ninth entry.
1133
1134    \begin{python}
1135    numslices=len(sine_table)-1
1136
1137    minval=0
1138    maxval=1.125    # The extra 0.25 is to account for the extra entry in the table
1139
1140    step=sup(maxval-minval)/numslices
1141    \end{python}
1142
1143    So the values $v$ from the input lie in the interval minval$\leq v <$maxval.
1144    \var{step} represents the gap (in the input range) between entries in the table.
1145    Now we produce our new \Data object.
1146
1147    \begin{python}
1148    result=x0.interpolateTable(sine_table, minval, step, toobig)
1149    \end{python}
1150    Any values which interpolate to larger than \var{toobig} will raise an exception.
1151
1152    Now for a 2D example.
1153    We will interpolate a surface such that the bottom edge is the sine curve described above.
1154    The amplitude of the curve decreases as we move towards the top edge.
1155
1156    Our interpolation table will have three rows.
1157    \begin{python}
1158    st=numpy.array(sine_table)
1159
1160    table=[st, 0.5*st, 0*st ]
1161    \end{python}
1162
1163    The use of numpy and multiplication here is just to save typing.
1164
1165    \begin{python}
1166    result2=x1.interpolateTable(table, 0, 0.55, x0, minval, step, toobig)
1167    \end{python}
1168
1169    In the 2D case, the params for the x1 direction (min=0, step=0.55) come first followed by the x0 data object and
1170    its params.
1171    In this case, the upper bound in the x1 direction is $1.10$ not $1$ so we don't need to add an extra row to the table.
1172
1173    \subsection{Saving Data as CSV}
1174    \index{saveDataCSV}
1175    \index{CSV}
1176    For simple post-processing, \Data objects can be saved in comma separated value format.
1177
1178    If \var{mydata1} and \var{mydata2} are scalar data, the following command:
1179    \begin{python}
1180    saveDataCSV('output.csv',U=mydata1, V=mydata2)
1181    \end{python}
1182    will record the values of mydata in \texttt{output.csv} in the following format:
1183    \begin{verbatim}
1184    U, V
1185    1.0000000e+0, 2.0000000e-1
1186    5.0000000e-0, 1.0000000e+1
1187    ...
1188    \end{verbatim}
1189
1190    The names of the keyword parameters form the names of columns in the ouput.
1191    If the data objects are over different function spaces, then saveDataCSV will attempt to
1192    interpolate to a common function space.
1193    If this is not possible, then an exception will be raised.
1194
1195    Output can be restricted using a scalar mask.
1196    \begin{python}
1198    \end{python}
1199    Will only output those rows which correspond to to positive values of \var{myscalar}.
1200    Some aspects of the output can be tuned using additional params.
1201    \begin{python}
1203    \end{python}
1204
1205    \begin{itemize}
1206     \item \var{append} - specifies that the output should be written to the end of an existing file.
1207    \item \var{sep} - defines the separator between fields.
1208    \item \var{csep} - defines the separator between components in the header line. For example between the components of a matrix.
1209    \end{itemize}
1210
1211    The above command would produce output like this:
1212    \begin{verbatim}
1213    e/0/0 e/1/0 e/0/1 e/1/1
1214    1.0000000000e+00 2.0000000000e+00 3.0000000000e+00 4.0000000000e+00
1215    ...
1216    \end{verbatim}
1217
1218
1219
1220  \subsection{\Operator Class}  \subsection{\Operator Class}