add back gdat_call to structure and add .help in tutorial description

git-svn-id: https://spcsvn.epfl.ch/repos/TCV/gdat/trunk@5147 d63d8f72-b253-0410-a779-e742ad2e26cf

crpptbx/TCV/gdat_tcv.m

@@ -61,7 +61,7 @@ function [gdat_data,gdat_params,error_status,varargout] = gdat_tcv(shot,data_req
 varargout{1}=cell(1,1);
 error_status=1;
 
-% construct default parameters structure
+% construct main default parameters structure
 gdat_params.data_request = '';
 default_machine = 'tcv';
 

crpptbx/gdat.m

@@ -77,9 +77,6 @@ if nargin>2
   end
 end
 
-gdat_data.data = [];
-% construct default parameters structure
-gdat_params.data_request = '';
 fusion_machine_defaultname=getenv('FUSION_MACHINE_DEFAULTNAME');
 default_machine = '';
 if ~isempty(fusion_machine_defaultname)
@@ -123,7 +120,7 @@ gdat_path = mfilename('fullpath');
 eval(['addpath ' gdat_path(1:end-4) upper(machine_eff)]);
 
 % copy gdat present call:
-gdat_data.gdat_call = [];
+gdat_call = [];
 if nargin==0
   subcall=['gdat;'];
 elseif nargin>=1
@@ -133,7 +130,7 @@ elseif nargin>=1
     subcall=['gdat(' shot ];
   else
     warning('type of 1st argument unexpected, should be numeric or char')
-    gdat_data.gdat_call = [];
+    gdat_call = [];
     return
   end
   if nargin>=2
@@ -152,15 +149,10 @@ elseif nargin>=1
   subcall = [subcall ');'];
 end
 
-gdat_data.gdat_call = [subcall ' % nargout = ' num2str(nargout)];
-gdat_data.gdat_params = gdat_params;
-if ~isfield(gdat_data.gdat_params,'doplot')
-  gdat_data.gdat_params.doplot = 0;
-end
+gdat_call = [subcall ' % nargout = ' num2str(nargout)];
 
 % Note: would need to check nargout to make call consistent, but to avoid this, each gdat_xxx should return at least an empty varargout: varargout{1}=cell(1);
 % copy subcall here so is last subnode
-
 try
   if nargin==0
     eval(['[gdat_data,gdat_params,error_status,varargout] = gdat_' lower(machine_eff) ';']);
@@ -176,6 +168,8 @@ catch
   return
 end
 
+gdat_data.gdat_call = gdat_call;
+
 if gdat_data.gdat_params.doplot
   % plot gdat_data versus 1st dim by default, if nb_dims<=2, otherwise do not plot
   if length(varargout)==0 || isempty(varargout{1})

demos/gdat_tutorial.m

@@ -7,8 +7,7 @@
 %
 % But sub-cases are also valid and explained below
 %
-% At this stage, you need to do the following to test it:
-addpath ~sauter/matlab/gdat/crpptbx_new
+
 %% getting the list of available predefined data_request names
 %
 gdat_data = gdat;
@@ -72,4 +71,12 @@ gdat_plot(gdat_data_te{3});
 gdat_data = gdat(48836,'eqdsk');
 disp(' ');disp('after "eqdsk"');disp(' gdat_data.gdat_params:');disp(gdat_data.gdat_params)
 % shows that 'time' should be given (can be an array) and 'zshift' (to shift vertically to zaxis=0 if 'zshift',1 is provided
-%
+% It also show you can give the cocos out you want, for example for CHEASE type coordinates you would do: 
\ No newline at end of file
+%     gdat_data = gdat(48836,'eqdsk','cocos',2);
+% (see O. Sauter and S. Y Medvedev, Tokamak Coordinate Conventions: COCOS , Comput. Phys. Commun. 184 (2013) 293 )
+%
+
+% gdat_params contains a sub-structure "help" which contains explanations
+% for the respective optional parameter specified in the gdat_params structure
+% In this case we have:
+disp(' ');disp('after "eqdsk"');disp(' gdat_data.gdat_params.help:');disp(gdat_data.gdat_params.help)

demos/html/gdat_tutorial.html

@@ -6,7 +6,7 @@
    <!--
 This HTML was auto-generated from MATLAB code.
 To make changes, update the MATLAB code and republish this document.
-      --><title>gdat_tutorial</title><meta name="generator" content="MATLAB 8.3"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.date" content="2015-09-15"><meta name="DC.source" content="gdat_tutorial.m"><style type="text/css">
+      --><title>gdat tutorial: some basic calls and functionalities</title><meta name="generator" content="MATLAB 8.3"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.date" content="2015-10-14"><meta name="DC.source" content="gdat_tutorial.m"><style type="text/css">
 html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;vertical-align:baseline;background:transparent}body{line-height:1}ol,ul{list-style:none}blockquote,q{quotes:none}blockquote:before,blockquote:after,q:before,q:after{content:'';content:none}:focus{outine:0}ins{text-decoration:none}del{text-decoration:line-through}table{border-collapse:collapse;border-spacing:0}
 
 html { min-height:100%; margin-bottom:1px; }
@@ -66,8 +66,7 @@ table td { padding:7px 5px; text-align:left; vertical-align:top; border:1px soli
 
 
 
-  </style></head><body><div class="content"><h2>Contents</h2><div><ul><li><a href="#1">gdat tutorial: some basic calls and functionalities</a></li><li><a href="#2">getting the list of available predefined data_request names</a></li><li><a href="#3">list of data_request names for a specific machine</a></li><li><a href="#4">a simple example: get plasma current</a></li><li><a href="#5">a 2D example with Te profiles</a></li><li><a href="#6">Explaination of main fields</a></li><li><a href="#7">Explanation of basic parameters fields of gdat_params</a></li></ul></div><h2>gdat tutorial: some basic calls and functionalities<a name="1"></a></h2><p>gdat calls in fact the main function MACHINE/gdat_machine.m within the gdat folder gdat can be call with one of the available "data_request" keyword or with a full trace_name</p><p>The basic call is: data_out_struct = gdat(shot,data_request,'option1',option1_val,...);</p><p>But sub-cases are also valid and explained below</p><p>At this stage, you need to do the following to test it:</p><pre class="codeinput">addpath <span class="string">~sauter/matlab/gdat/crpptbx_new</span>
-</pre><h2>getting the list of available predefined data_request names<a name="2"></a></h2><pre class="codeinput">gdat_data = gdat;
+  </style></head><body><div class="content"><h1>gdat tutorial: some basic calls and functionalities</h1><!--introduction--><p>gdat calls in fact the main function MACHINE/gdat_machine.m within the gdat folder gdat can be call with one of the available "data_request" keyword or with a full trace_name</p><p>The basic call is: data_out_struct = gdat(shot,data_request,'option1',option1_val,...);</p><p>But sub-cases are also valid and explained below</p><!--/introduction--><h2>Contents</h2><div><ul><li><a href="#1">getting the list of available predefined data_request names</a></li><li><a href="#2">list of data_request names for a specific machine</a></li><li><a href="#3">a simple example: get plasma current</a></li><li><a href="#4">a 2D example with Te profiles</a></li><li><a href="#5">Explaination of main fields</a></li><li><a href="#6">Explanation of basic parameters fields of gdat_params</a></li></ul></div><h2>getting the list of available predefined data_request names<a name="1"></a></h2><pre class="codeinput">gdat_data = gdat;
 <span class="comment">%</span>
 <span class="comment">% This is the simplest call and returns 3 useful information:</span>
 gdat_data.gdat_request <span class="comment">% contains the list of available data_request names</span>
@@ -100,7 +99,8 @@ ans =
     'nel'
     'ne_rho'
     'nete_rho'
-    'ni'
+    'psi_axis'
+    'psi_edge'
     'powers'
     'q0'
     'q95'
@@ -114,8 +114,6 @@ ans =
     'sxr'
     'te'
     'te_rho'
-    'ti'
-    'transp'
     'vloop'
     'volume'
     'volume_rho'
@@ -130,6 +128,8 @@ ans =
          machine: 'tcv'
           doplot: 0
            liuqe: 1
+        nverbose: 1
+            help: [1x1 struct]
 
 
 ans =
@@ -141,57 +141,15 @@ ans =
 
 gdat; % nargout = 1
 
-</pre><h2>list of data_request names for a specific machine<a name="3"></a></h2><pre class="codeinput">gdat_data = gdat(<span class="string">'machine'</span>,<span class="string">'aug'</span>);
+</pre><h2>list of data_request names for a specific machine<a name="2"></a></h2><pre class="codeinput">gdat_data = gdat(<span class="string">'machine'</span>,<span class="string">'aug'</span>);
 gdat_data.gdat_request
 </pre><pre class="codeoutput">
-ans = 
+ans =
 
-    'a_minor'
-    'b0'
-    'beta'
-    'betan'
-    'betap'
-    'cxrs'
-    'delta'
-    'delta_bottom'
-    'delta_top'
-    'ece'
-    'eqdsk'
-    'halpha'
-    'ioh'
-    'ip'
-    'kappa'
-    'mhd'
-    'ne'
-    'neint'
-    'nel'
-    'ne_rho'
-    'nete_rho'
-    'ni'
-    'powers'
-    'q0'
-    'q95'
-    'qedge'
-    'q_rho'
-    'rgeom'
-    'rhotor_edge'
-    'rhotor'
-    'rhovol'
-    'rmag'
-    'sxr'
-    'te'
-    'te_rho'
-    'ti'
-    'transp'
-    'vloop'
-    'volume'
-    'volume_rho'
-    'zeff'
-    'zgeom'
-    'zmag'
-    'equil'
+     ''
 
-</pre><h2>a simple example: get plasma current<a name="4"></a></h2><pre class="codeinput">gdat_data = gdat(48836,<span class="string">'ip'</span>); <span class="comment">% shot number is for TCV (default machine if run at CRPP)</span>
+
+</pre><h2>a simple example: get plasma current<a name="3"></a></h2><pre class="codeinput">gdat_data = gdat(48836,<span class="string">'ip'</span>); <span class="comment">% shot number is for TCV (default machine if run at CRPP)</span>
 gdat_data = gdat(48836,<span class="string">'ip'</span>,<span class="string">'doplot'</span>,1);
 gdat_data = gdat(48836,<span class="string">'Ip'</span>);
 <span class="comment">% Note that the return data_request name is 'ip', since lower case is used throughout</span>
@@ -201,10 +159,10 @@ ans =
 
 ip
 
-</pre><img vspace="5" hspace="5" src="gdat_tutorial_01.png" alt=""> <h2>a 2D example with Te profiles<a name="5"></a></h2><pre class="codeinput">gdat_data = gdat(48836,<span class="string">'te'</span>); <span class="comment">% return thomson data, thus versus Z (vertical height) of local measurements</span>
+</pre><img vspace="5" hspace="5" src="gdat_tutorial_01.png" alt=""> <h2>a 2D example with Te profiles<a name="4"></a></h2><pre class="codeinput">gdat_data = gdat(48836,<span class="string">'te'</span>); <span class="comment">% return thomson data, thus versus Z (vertical height) of local measurements</span>
 gdat_data = gdat(48836,<span class="string">'te'</span>,<span class="string">'doplot'</span>,1); <span class="comment">% default plot is always versus time, using gdat_data.t</span>
 <span class="comment">% for more specific plots, use gdat_plot(gdat_data,...) function</span>
-</pre><img vspace="5" hspace="5" src="gdat_tutorial_02.png" alt=""> <h2>Explaination of main fields<a name="6"></a></h2><pre class="codeinput">gdat_data = gdat(48836,<span class="string">'te'</span>);
+</pre><img vspace="5" hspace="5" src="gdat_tutorial_02.png" alt=""> <h2>Explaination of main fields<a name="5"></a></h2><pre class="codeinput">gdat_data = gdat(48836,<span class="string">'te'</span>);
 gdat_data
 <span class="comment">% The following fields are always present:</span>
 <span class="comment">% gdat_data.data  % (as well as .units) providing the data</span>
@@ -235,14 +193,14 @@ gdat_data =
                    shot: 48836
            gdat_request: 'te'
             gdat_params: [1x1 struct]
-          data_fullpath: '\results::thomson:te'
+          data_fullpath: '\results::thomson:te; error_bar'
     request_description: 'Electron temperature'
                   label: 'Te'
-              error_bar: [23x49 double]
             mapping_for: [1x1 struct]
+              error_bar: [23x49 double]
               gdat_call: 'gdat(48836,'te'); % nargout = 1'
 
-</pre><h2>Explanation of basic parameters fields of gdat_params<a name="7"></a></h2><pre class="codeinput">gdat_data = gdat(48836,<span class="string">'te'</span>);
+</pre><h2>Explanation of basic parameters fields of gdat_params<a name="6"></a></h2><pre class="codeinput">gdat_data = gdat(48836,<span class="string">'te'</span>);
 disp(<span class="string">' '</span>);disp(<span class="string">'after "te"'</span>);disp(<span class="string">' gdat_data.gdat_params:'</span>);disp(gdat_data.gdat_params) <span class="comment">% at this stage contains few elements, will depend on specific data_request</span>
 <span class="comment">%</span>
 <span class="comment">% gdat_params should contain all the information necessary to recall gdat</span>
@@ -260,7 +218,15 @@ gdat_plot(gdat_data_te{3});
 gdat_data = gdat(48836,<span class="string">'eqdsk'</span>);
 disp(<span class="string">' '</span>);disp(<span class="string">'after "eqdsk"'</span>);disp(<span class="string">' gdat_data.gdat_params:'</span>);disp(gdat_data.gdat_params)
 <span class="comment">% shows that 'time' should be given (can be an array) and 'zshift' (to shift vertically to zaxis=0 if 'zshift',1 is provided</span>
+<span class="comment">% It also show you can give the cocos out you want, for example for CHEASE type coordinates you would do:</span>
+<span class="comment">%     gdat_data = gdat(48836,'eqdsk','cocos',2);</span>
+<span class="comment">% (see O. Sauter and S. Y Medvedev, Tokamak Coordinate Conventions: COCOS , Comput. Phys. Commun. 184 (2013) 293 )</span>
 <span class="comment">%</span>
+
+<span class="comment">% gdat_params contains a sub-structure "help" which contains explanations</span>
+<span class="comment">% for the respective optional parameter specified in the gdat_params structure</span>
+<span class="comment">% In this case we have:</span>
+disp(<span class="string">' '</span>);disp(<span class="string">'after "eqdsk"'</span>);disp(<span class="string">' gdat_data.gdat_params.help:'</span>);disp(gdat_data.gdat_params.help)
 </pre><pre class="codeoutput"> 
 after "te"
  gdat_data.gdat_params:
@@ -268,16 +234,10 @@ after "te"
          machine: 'tcv'
           doplot: 0
            liuqe: 1
+        nverbose: 1
+            help: [1x1 struct]
+            edge: 0
 
-"time" is expected as an option, choose default time = 1
-
-time_eff =
-
-     1
-
-do not calculate BR, BZ, Bphi, etc
-Wrote /tmp/sauter/EQDSK_48836t1.0000_COCOS02
-Wrote /tmp/sauter/EQDSK_48836t1.0000_COCOS02_IpB0positive
 Wrote /tmp/sauter/EQDSK_48836t1.0000_COCOS17
 Wrote /tmp/sauter/EQDSK_48836t1.0000_COCOS17_IpB0positive
  
@@ -287,8 +247,23 @@ after "eqdsk"
          machine: 'tcv'
           doplot: 0
            liuqe: 1
+        nverbose: 1
+            help: [1x1 struct]
             time: 1
           zshift: 0
+           cocos: 17
+
+ 
+after "eqdsk"
+ gdat_data.gdat_params.help:
+    data_request: 'automatically filled in by gdat, name of request used i...'
+         machine: 'machine name like 'TCV', 'AUG', case insensitive'
+          doplot: '0 (default), if 1 calls gdat_plot for a new figure, -1 ...'
+           liuqe: 'liuqe version 1 (default), 2, 3 for LIUQE1, 2, 3 resp. ...'
+        nverbose: '1 (default) displays warnings, 0: only errors, &gt;=3: dis...'
+            time: 'time(s) value(s) if relevant, for example eqdsk is prov...'
+          zshift: 'vertical shift of equilibrium, either for eqdsk or for ...'
+           cocos: 'cocos value desired in output, uses eqdsk_cocos_transfo...'
 
 </pre><p class="footer"><br><a href="http://www.mathworks.com/products/matlab/">Published with MATLAB&reg; R2014a</a><br></p></div><!--
 ##### SOURCE BEGIN #####
@@ -301,8 +276,7 @@ after "eqdsk"
 %
 % But sub-cases are also valid and explained below
 %
-% At this stage, you need to do the following to test it:
-addpath ~sauter/matlab/gdat/crpptbx_new
+
 %% getting the list of available predefined data_request names
 %
 gdat_data = gdat;
@@ -366,6 +340,15 @@ gdat_plot(gdat_data_te{3});
 gdat_data = gdat(48836,'eqdsk');
 disp(' ');disp('after "eqdsk"');disp(' gdat_data.gdat_params:');disp(gdat_data.gdat_params)
 % shows that 'time' should be given (can be an array) and 'zshift' (to shift vertically to zaxis=0 if 'zshift',1 is provided
+% It also show you can give the cocos out you want, for example for CHEASE type coordinates you would do: 
+%     gdat_data = gdat(48836,'eqdsk','cocos',2);
+% (see O. Sauter and S. Y Medvedev, Tokamak Coordinate Conventions: COCOS , Comput. Phys. Commun. 184 (2013) 293 )
 %
+
+% gdat_params contains a sub-structure "help" which contains explanations
+% for the respective optional parameter specified in the gdat_params structure
+% In this case we have:
+disp(' ');disp('after "eqdsk"');disp(' gdat_data.gdat_params.help:');disp(gdat_data.gdat_params.help)
+
 ##### SOURCE END #####
 --></body></html>
\ No newline at end of file