Differential_equations doc: warning fix
[scilab.git] / scilab / modules / differential_equations / help / ja_JP / dae.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * ...
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dae" xml:lang="ja">
15     <refnamediv>
16         <refname>dae</refname>
17         <refpurpose>微分代数方程式ソルバ</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>呼び出し手順</title>
21         <synopsis> y=dae(initial,t0,t,res)
22             [y [,hd]]=dae(initial,t0,t [,rtol, [atol]],res [,jac] [,hd])
23             [y,rd]=dae("root",initial,t0,t,res,ng,surface)
24             [y ,rd [,hd]]=dae("root",initial,t0,t [,rtol, [atol]],res [,jac], ng, surface [,hd])
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>パラメータ</title>
29         <variablelist>
30             <varlistentry>
31                 <term>initial</term>
32                 <listitem>
33                     <para>
34                         列ベクトル. <literal>x0 </literal>または
35                         <literal>[x0;xdot0]</literal> に等しくなります.
36                         ただし, <literal>x0</literal>は初期時刻<literal>t0</literal>における状態量の値,
37                         <literal>ydot0</literal>は状態量の微分の初期値またはその推定値(下記参照)です.
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>t0</term>
43                 <listitem>
44                     <para>実数, 初期時刻.</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>t</term>
49                 <listitem>
50                     <para>実数のスカラーまたはベクトル. 解を計算する時刻を指定します.
51                         <literal>
52                             <link linkend="daeoptions">%DAEOPTIONS</link>(2)=1
53                         </literal>
54                         と設定することにより
55                         DAEの各ステップで解が得られることに注意してください.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>rtol</term>
61                 <listitem>
62                     <para>
63                         実数のスカラーまたは<literal>x0</literal>と同じ大きさの
64                         列ベクトル. 解の相対許容誤差.
65                         <literal>rtol</literal>がベクトルの場合,
66                         状態量の各要素毎に許容誤差が指定されます.
67                     </para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>atol</term>
72                 <listitem>
73                     <para>
74                         実数のスカラーまたは<literal>x0</literal>と同じ大きさの
75                         列ベクトル. 解の絶対許容誤差.
76                         <literal>rtol</literal>がベクトルの場合,
77                         状態量の各要素毎に許容誤差が指定されます.
78                     </para>
79                 </listitem>
80             </varlistentry>
81             <varlistentry>
82                 <term>res</term>
83                 <listitem>
84                     <para>
85                         <link linkend="external" role="" version="">外部ルーチン</link>.
86                         <literal>g(t,y,ydot)</literal>の値を計算します. 以下のようになります
87                     </para>
88                     <variablelist>
89                         <varlistentry>
90                             <term>Scilab関数</term>
91                             <listitem>
92                                 <para>この場合, その呼出し手順を
93                                     <literal>[r,ires]=res(t,x,xdot)</literal> とする
94                                     必要があり,<literal>res</literal> は
95                                     残差<literal>r=g(t,x,xdot)</literal> とエラーフラグ
96                                     <literal>ires</literal>を返す必要があります.
97                                     <literal>res</literal>が<literal>r</literal>の計算に
98                                     成功した場合には<literal>ires = 0</literal>,
99                                     <literal>(t,x,xdot)</literal>のローカルな残差が定義されない
100                                     場合には <literal>=-1</literal>,
101                                     パラメータが許容範囲外の場合は <literal>=-2</literal> となります.
102                                 </para>
103                             </listitem>
104                         </varlistentry>
105                         <varlistentry>
106                             <term>リスト</term>
107                             <listitem>
108                                 <para>外部ルーチンのこの形式は
109                                     関数にパラメータを指定する際に使用されます.
110                                     以下のような形式とします:
111                                 </para>
112                                 <programlisting role=""><![CDATA[
113 list(res,p1,p2,...)
114  ]]></programlisting>
115                                 <para>
116                                     ただし,ここで関数<literal>res</literal>の呼び出し手順は以下のようになります
117                                 </para>
118                                 <programlisting role=""><![CDATA[
119 r=res(t,y,ydot,p1,p2,...)
120  ]]></programlisting>
121                                 <para>
122                                     この場合も<literal>res</literal> は
123                                     <literal>(t,x,xdot,x1,x2,...)</literal>の関数として残差の値を返し,
124                                     p1,p2,... は関数のパラメータです.
125                                 </para>
126                             </listitem>
127                         </varlistentry>
128                         <varlistentry>
129                             <term>文字列</term>
130                             <listitem>
131                                 <para>CまたはFortranルーチンの名前を指します.
132                                     &lt;r_name&gt; が指定した名前であると仮定します.
133                                 </para>
134                                 <itemizedlist>
135                                     <listitem>
136                                         <para>Fortranの呼出し手順は以下のようにします</para>
137                                         <para>
138                                             <literal>&lt;r_name&gt;(t,x,xdot,res,ires,rpar,ipar)</literal>
139                                         </para>
140                                         <para>
141                                             <literal>double precision
142                                                 t,x(*),xdot(*),res(*),rpar(*)
143                                             </literal>
144                                         </para>
145                                         <para>
146                                             <literal>integer ires,ipar(*)</literal>
147                                         </para>
148                                     </listitem>
149                                     <listitem>
150                                         <para>Cの呼出し手順は以下のようにします</para>
151                                         <para>C2F(&lt;r_name&gt;)(double *t, double *x, double
152                                             *xdot, double *res, integer *ires, double *rpar, integer
153                                             *ipar)
154                                         </para>
155                                     </listitem>
156                                 </itemizedlist>
157                                 <para>ただし,</para>
158                                 <itemizedlist>
159                                     <listitem>
160                                         <para>
161                                             <literal>t</literal> はカレントの時刻
162                                         </para>
163                                     </listitem>
164                                     <listitem>
165                                         <para>
166                                             <literal>x</literal>は状態量の配列
167                                         </para>
168                                     </listitem>
169                                     <listitem>
170                                         <para>
171                                             <literal>xdot</literal> は状態量の微分の配列
172                                         </para>
173                                     </listitem>
174                                     <listitem>
175                                         <para>res は残差の配列</para>
176                                     </listitem>
177                                     <listitem>
178                                         <para>
179                                             <literal>ires</literal>は実行インジケータ
180                                         </para>
181                                     </listitem>
182                                     <listitem>
183                                         <para>
184                                             <literal>rpar</literal> は浮動小数点数の
185                                             パラメータ値の配列で, 必要ですが <literal>dae</literal> 関数により
186                                             設定できないもの
187                                         </para>
188                                     </listitem>
189                                     <listitem>
190                                         <para>
191                                             <literal>ipar</literal> は整数の
192                                             パラメータ値の配列で, 必要ですが <literal>dae</literal> 関数により
193                                             設定できないもの
194                                         </para>
195                                     </listitem>
196                                 </itemizedlist>
197                             </listitem>
198                         </varlistentry>
199                     </variablelist>
200                 </listitem>
201             </varlistentry>
202             <varlistentry>
203                 <term>jac</term>
204                 <listitem>
205                     <para>
206                         <link linkend="external" role="" version="">外部ルーチン</link>.
207                         指定したパラメータの値 <literal>cj</literal>を用いて
208                         <literal>dg/dx+cj*dg/dxdot</literal>の値を計算します. 以下のようになります
209                     </para>
210                     <variablelist>
211                         <varlistentry>
212                             <term>Scilab関数</term>
213                             <listitem>
214                                 <para>呼出し手順を
215                                     <literal>r=jac(t,x,xdot,cj)</literal> とする
216                                     必要があり,
217                                     <literal>jac</literal>関数は
218                                     <literal>r=dg(t,x,xdot)/dy+cj*dg(t,x,xdot)/dxdot</literal>
219                                     を返す必要があります.
220                                     ただし,<literal>cj</literal>は実数スカラーです.
221                                 </para>
222                             </listitem>
223                         </varlistentry>
224                         <varlistentry>
225                             <term>リスト</term>
226                             <listitem>
227                                 <para>外部ルーチンのこの形式は
228                                     関数にパラメータを指定する際に使用されます.
229                                     以下のような形式とします:
230                                 </para>
231                                 <programlisting role=""><![CDATA[
232 list(jac,p1,p2,...)
233  ]]></programlisting>
234                                 <para>
235                                     ただしこの場合の関数<literal>jac</literal>の呼び出し手順は
236                                     以下となります
237                                 </para>
238                                 <programlisting role=""><![CDATA[
239 r=jac(t,x,xdot,p1,p2,...)
240  ]]></programlisting>
241                                 <para>
242                                     この場合でも<literal>jac</literal> は,
243                                     <literal>(t,x,xdot,cj,p1,p2,...)</literal>の関数として
244                                     <literal>dg/dx+cj*dg/dxdot</literal>を返します.
245                                 </para>
246                             </listitem>
247                         </varlistentry>
248                         <varlistentry>
249                             <term>文字列</term>
250                             <listitem>
251                                 <para>CまたはFortranルーチンの名前を指します.
252                                     &lt;j_name&gt; が指定した名前であると仮定します.
253                                 </para>
254                                 <itemizedlist>
255                                     <listitem>
256                                         <para>Fortranの呼出し手順は以下のようにします</para>
257                                         <para>
258                                             <literal>&lt;j_name&gt;(t, x, xdot, r, cj, ires,
259                                                 rpar, ipar)
260                                             </literal>
261                                         </para>
262                                         <para>
263                                             <literal>double precision t, x(*), xdot(*), r(*),
264                                                 ci, rpar(*)
265                                             </literal>
266                                         </para>
267                                         <para>
268                                             <literal>integer ires, ipar(*)</literal>
269                                         </para>
270                                     </listitem>
271                                     <listitem>
272                                         <para>Cの呼出し手順は以下のようにします</para>
273                                         <para>C2F(&lt;j_name&gt;)(double *t, double *x, double
274                                             *xdot, double *r, double *cj,
275                                         </para>
276                                         <para>integer *ires, double *rpar, integer *ipar)</para>
277                                     </listitem>
278                                 </itemizedlist>
279                                 <para>
280                                     ただし <literal>t</literal>, x, xdot, ires, rpar, ipar
281                                     は上記と似た定義を有し, r は配列の結果です.
282                                 </para>
283                             </listitem>
284                         </varlistentry>
285                     </variablelist>
286                 </listitem>
287             </varlistentry>
288             <varlistentry>
289                 <term>surface</term>
290                 <listitem>
291                     <para>
292                         <link linkend="external" role="" version="">外部ルーチン</link>.
293                         <literal>ng</literal>個の要素を有する列ベクトル
294                         <literal>surface(t,x)</literal>の値を計算します.
295                         各要素は面(surface)を定義します.
296                     </para>
297                     <variablelist>
298                         <varlistentry>
299                             <term>Scilab関数</term>
300                             <listitem>
301                                 <para>
302                                     その呼び出し手順は<literal>r=surface(t,x)</literal>とする
303                                     必要があり,この関数は <literal>ng</literal>個の要素を有する
304                                     ベクトルを返す必要があります.
305                                 </para>
306                             </listitem>
307                         </varlistentry>
308                         <varlistentry>
309                             <term>リスト</term>
310                             <listitem>
311                                 <para>外部ルーチンのこの形式は
312                                     関数にパラメータを指定する際に使用されます.
313                                     以下のような形式とします:
314                                 </para>
315                                 <programlisting role=""><![CDATA[
316 list(surface,p1,p2,...)
317  ]]></programlisting>
318                                 <para>
319                                     ただしこの場合の関数<literal>surface</literal>の呼び出し手順は
320                                     以下となります
321                                 </para>
322                                 <programlisting role=""><![CDATA[
323 r=surface(t,x,p1,p2,...)
324  ]]></programlisting>
325                             </listitem>
326                         </varlistentry>
327                         <varlistentry>
328                             <term>文字列</term>
329                             <listitem>
330                                 <para>CまたはFortranルーチンの名前を指します.
331                                     &lt;s_name&gt; が指定した名前であると仮定します,
332                                 </para>
333                                 <itemizedlist>
334                                     <listitem>
335                                         <para>Fortranの呼出し手順は以下のようにします</para>
336                                         <para>
337                                             <literal>&lt;r_name&gt;(nx, t, x, ng, r, rpar,
338                                                 ipar)
339                                             </literal>
340                                         </para>
341                                         <para>
342                                             <literal>double precision t, x(*), r(*),
343                                                 rpar(*)
344                                             </literal>
345                                         </para>
346                                         <para>
347                                             <literal>integer nx, ng,ipar(*)</literal>
348                                         </para>
349                                     </listitem>
350                                     <listitem>
351                                         <para>Cの呼出し手順は以下のようにします</para>
352                                         <para>C2F(&lt;r_name&gt;)(double *t, double *x, double
353                                             *xdot, double *r, double *cj,
354                                         </para>
355                                         <para>integer *ires, double *rpar, integer *ipar)</para>
356                                     </listitem>
357                                 </itemizedlist>
358                                 <para>
359                                     ただし,<literal>t</literal>, x, rpar, ipar は
360                                     上記と同じ定義を有し,<literal>ng </literal> は
361                                     surfacesの数, <literal>nx</literal> は状態量の次元,
362                                     r は結果の配列です.
363                                 </para>
364                             </listitem>
365                         </varlistentry>
366                     </variablelist>
367                 </listitem>
368             </varlistentry>
369             <varlistentry>
370                 <term>rd</term>
371                 <listitem>
372                     <para>
373                         2個のエントリ <literal>[times num]</literal>を有するベクトル.
374                         <literal>times</literal> は面が交差した時刻の値,
375                         <literal>num</literal> は交差した面の数です
376                     </para>
377                 </listitem>
378             </varlistentry>
379             <varlistentry>
380                 <term>hd</term>
381                 <listitem>
382                     <para>実数のベクトル,
383                         <literal>dae</literal> コンテキストを保持する出力.
384                         (ホットスタートで)積分を再開するための入力引数として使用可能です.
385                     </para>
386                 </listitem>
387             </varlistentry>
388             <varlistentry>
389                 <term>y</term>
390                 <listitem>
391                     <para>
392                         実数の行列.
393                         <literal>
394                             <link linkend="daeoptions">%DAEOPTIONS</link>(2)=1
395                         </literal>
396                         の場合, 各列
397                         はベクトル <literal>[t;x(t);xdot(t)]</literal> です.
398                         ただし, <literal>t</literal> は解が計算された時刻です.
399                         それ以外の場合, <literal>y</literal> はベクトル
400                         <literal>[x(t);xdot(t)]</literal>です.
401                     </para>
402                 </listitem>
403             </varlistentry>
404         </variablelist>
405     </refsection>
406     <refsection>
407         <title>説明</title>
408         <para>
409             <literal>dae</literal> 関数は,
410             陰的な微分方程式積分用に設計された
411             <link linkend="dassl">dassl</link> および <link linkend="dasrt">dasrt</link>
412             関数の上位に構築されたゲートウエイです.
413         </para>
414         <programlisting role=""><![CDATA[
415 g(t,x,xdot)=0
416 x(t0)=x0  and   xdot(t0)=xdot0
417  ]]></programlisting>
418         <para>
419             引数<literal>initial</literal>に<literal>xdot0</literal> が指定されない場合,
420             dae関数は g(t,x0,xdot0)=0 を解くことによりこれを計算しようとします.
421         </para>
422         <para>
423             <literal>xdot0</literal> が <literal>initial</literal> 引数で指定された場合,
424             g(t,x0,xdot0)=0 を満たす互換性がある微係数または近似値の
425             どちらかとなります.
426             後者の場合,
427             <literal>
428                 <link linkend="daeoptions">%DAEOPTIONS</link>(7)
429             </literal>
430             を
431             1 に設定する必要があります.
432         </para>
433         <para>Scilab および C でコーディングされた外部ルーチンを使用する詳細な例については,
434             <literal>modules/differential_equations/tests/unit_tests/dassldasrt.tst</literal>
435             で提供されています.
436         </para>
437     </refsection>
438     <refsection>
439         <title>例</title>
440         <programlisting role="example"><![CDATA[
441 // Scilabコードを使用する例
442 function [r,ires]=chemres(t,y,yd)
443     r(1) = -0.04*y(1) + 1d4*y(2)*y(3) - yd(1);
444     r(2) =  0.04*y(1) - 1d4*y(2)*y(3) - 3d7*y(2)*y(2) - yd(2);
445     r(3) =       y(1) +     y(2)      + y(3)-1;
446     ires =  0;
447 endfunction
448 function pd=chemjac(x,y,yd,cj)
449     pd=[-0.04-cj , 1d4*y(3)               , 1d4*y(2);
450          0.04    ,-1d4*y(3)-2*3d7*y(2)-cj ,-1d4*y(2);
451          1       , 1                      , 1       ]
452 endfunction
453
454 x0=[1; 0; 0];
455 xd0=[-0.04; 0.04; 0];
456 t=[1.d-5:0.02:.4, 0.41:.1:4, 40, 400, 4000, 40000, 4d5, 4d6, 4d7, 4d8, 4d9, 4d10];
457
458 y=dae([x0,xd0],0,t,chemres);// 指定した観測時刻での点を返す
459
460 %DAEOPTIONS=list([],1,[],[],[],0,0); // dae メッシュ点を返すかどうかを確認
461 y=dae([x0,xd0],0,4d10,chemres); // ヤコビアン指定なし
462 y=dae([x0,xd0],0,4d10,chemres,chemjac); // ヤコビアン指定あり
463
464 // C コードの例 (Cコンパイラが必要) --------------------------------------------------
465 //-1- Cコードを TMPDIR に作成 - Vanderpol 方程式, 陰形式
466 code=['#include <math.h>'
467       'void res22(double *t,double *y,double *yd,double *res,int *ires,double *rpar,int *ipar)'
468       '{res[0] = yd[0] - y[1];'
469       ' res[1] = yd[1] - (100.0*(1.0 - y[0]*y[0])*y[1] - y[0]);}'
470       ' '
471       'void jac22(double *t,double *y,double *yd,double *pd,double *cj,double *rpar,int *ipar)'
472       '{pd[0]=*cj - 0.0;'
473       ' pd[1]=    - (-200.0*y[0]*y[1] - 1.0);'
474       ' pd[2]=    - 1.0;'
475       ' pd[3]=*cj - (100.0*(1.0 - y[0]*y[0]));}'
476       ' '
477       'void gr22(int *neq, double *t, double *y, int *ng, double *groot, double *rpar, int *ipar)'
478       '{ groot[0] = y[0];}']
479 mputl(code,TMPDIR+'/t22.c')
480 //-2- コンパイルの後,ロード
481 ilib_for_link(['res22' 'jac22' 'gr22'],'t22.c',[],'c',[],TMPDIR+'/t22loader.sce');
482 exec(TMPDIR+'/t22loader.sce')
483 //-3- 実行
484 rtol=[1.d-6;1.d-6];atol=[1.d-6;1.d-4];
485 t0=0;y0=[2;0];y0d=[0;-2];t=[20:20:200];ng=1;
486 //簡単なシミュレーション
487 t=0:0.003:300;
488 yy=dae([y0,y0d],t0,t,atol,rtol,'res22','jac22');
489 clf();plot(yy(1,:),yy(2,:))
490 //find first point where yy(1)=0
491 [yy,nn,hotd]=dae("root",[y0,y0d],t0,300,atol,rtol,'res22','jac22',ng,'gr22');
492 plot(yy(1,1),yy(2,1),'r+')
493 xstring(yy(1,1)+0.1,yy(2,1),string(nn(1)))
494
495 //次の点までホットリスタート
496 t01=nn(1);[pp,qq]=size(yy);y01=yy(2:3,qq);y0d1=yy(3:4,qq);
497 [yy,nn,hotd]=dae("root",[y01,y0d1],t01,300,atol,rtol,'res22','jac22',ng,'gr22',hotd);
498 plot(yy(1,1),yy(2,1),'r+')
499 xstring(yy(1,1)+0.1,yy(2,1),string(nn(1)))
500  ]]></programlisting>
501     </refsection>
502     <refsection role="see also">
503         <title>参照</title>
504         <simplelist type="inline">
505             <member>
506                 <link linkend="ode">ode</link>
507             </member>
508             <member>
509                 <link linkend="daeoptions">daeoptions</link>
510             </member>
511             <member>
512                 <link linkend="dassl">dassl</link>
513             </member>
514             <member>
515                 <link linkend="impl">impl</link>
516             </member>
517             <member>
518                 <link linkend="fort">fort</link>
519             </member>
520             <member>
521                 <link linkend="link">link</link>
522             </member>
523             <member>
524                 <link linkend="external">external</link>
525             </member>
526         </simplelist>
527     </refsection>
528 </refentry>