STUDY - Revision history

Jpye at 00:58, 10 March 2026

2026-03-10T00:58:53Z

← Older revision		Revision as of 00:58, 10 March 2026
Line 33:		Line 33:
	* <code>NOW</code> is optional.		* <code>NOW</code> is optional.
	* The varied variable may also appear in the observed variable list.		* The varied variable may also appear in the observed variable list.
			* When <code>VARY</code> is present, the varied variable is always included first in the Observer and in CLI tabular output, without duplication.
	* The current solver and options are taken from the existing GUI state and/or earlier METHOD <code>SOLVER</code> / <code>OPTION</code> statements. They are not restated inside <code>STUDY</code>.		* The current solver and options are taken from the existing GUI state and/or earlier METHOD <code>SOLVER</code> / <code>OPTION</code> statements. They are not restated inside <code>STUDY</code>.

Line 58:		Line 59:
	* <code>NOW</code> is accepted but has no additional effect in the CLI path; varying studies already execute immediately.		* <code>NOW</code> is accepted but has no additional effect in the CLI path; varying studies already execute immediately.
	* Output is tabular.		* Output is tabular.
			* The first column is always the varied variable.
	* Column headers include units of measurement.		* Column headers include units of measurement.
	* If <code>FILE</code> is present, the table is written there and a note is emitted telling the user where it went.		* If <code>FILE</code> is present, the table is written there and a note is emitted telling the user where it went.
Line 73:		Line 75:
	* If no Observer exists yet, one is created.		* If no Observer exists yet, one is created.
	* The observed variables are added to the active Observer.		* The observed variables are added to the active Observer.
			* If <code>VARY</code> is present, the varied variable is added first if it is not already present.
	* If <code>VARY</code> is omitted, the Observer is populated and no Study dialog is opened.		* If <code>VARY</code> is omitted, the Observer is populated and no Study dialog is opened.
	* If <code>VARY</code> is present, the Study dialog is opened with the variable, bounds, stepping mode, distribution, and optional <code>RUN</code> method pre-populated.		* If <code>VARY</code> is present, the Study dialog is opened with the variable, bounds, stepping mode, distribution, and optional <code>RUN</code> method pre-populated.

Jpye at 13:11, 9 March 2026

2026-03-09T13:11:44Z

← Older revision		Revision as of 13:11, 9 March 2026
Line 1:		Line 1:
	{{~~missing~~}}		<code>STUDY</code> is a METHOD-language statement for preparing or executing a parametric study from inside a model method such as <code>on_load</code>.

			<span id="syntax"></span>
			== Syntax ==

			<pre class="ascend">STUDY observed_var_list
			[VARY var FROM lower TO upper (STEPS n [LINEAR\|LOG] \| STEP delta \| RATIO r)]
			[RUN method_name]
			[NOW]
			[FILE "path"];</pre>
			Examples:

			<pre class="ascend">STUDY accel_required, time_run;

			STUDY accel_required, time_run
			VARY time_run FROM 2 {s} TO 6 {s} STEPS 4
			NOW
			FILE "study.tsv";

			STUDY y, x VARY x FROM 1 TO 10 STEP 0.1;
			STUDY y, x VARY x FROM 1 TO 10 RATIO 1.1;
			STUDY y, x VARY x FROM 1 TO 10 STEPS 8 LOG RUN reset;</pre>
			<span id="semantics"></span>

			See more examples in {{srcdir\|models/test/slvreq}}.

			== Semantics ==

			* The observed variable list is required.
			* <code>VARY</code> is optional.
			* <code>RUN method_name</code> is optional and is executed before each study point.
			* <code>FILE</code> is optional.
			* <code>NOW</code> is optional.
			* The varied variable may also appear in the observed variable list.
			* The current solver and options are taken from the existing GUI state and/or earlier METHOD <code>SOLVER</code> / <code>OPTION</code> statements. They are not restated inside <code>STUDY</code>.

			Stepping modes:

			* <code>STEPS n</code> means <code>n</code> intervals with both endpoints included.
			* <code>STEP delta</code> uses a linear increment.
			* <code>RATIO r</code> uses a logarithmic/geometric progression.
			* <code>STEPS n LOG</code> requests logarithmic spacing.
			* <code>STEPS n</code> without <code>LOG</code> uses linear spacing.

			Validation rules:

			* <code>STEP</code> must be non-zero and must move from the lower bound toward the upper bound.
			* <code>RATIO</code> must be positive, not equal to <code>1</code>, and must move from the lower bound toward the upper bound.
			* Logarithmic studies require both bounds to be positive.

			<span id="a4-run"></span>
			== <code>./a4 run</code> ==

			In the <code>ascxx</code> / CLI path, <code>STUDY</code> is interpreted in two different ways depending on whether <code>VARY</code> is present.

			* If <code>VARY</code> is present, the requested cases are solved in sequence.
			* If <code>RUN</code> is present, the named method is run before each study point.
			* <code>NOW</code> is accepted but has no additional effect in the CLI path; varying studies already execute immediately.
			* Output is tabular.
			* Column headers include units of measurement.
			* If <code>FILE</code> is present, the table is written there and a note is emitted telling the user where it went.
			* If <code>FILE</code> is omitted, the table is written to standard output.
			* If <code>VARY</code> is omitted, the observed variables are stored as the model’s default post-solve print list. <code>a4 run</code> then prints them after the main solve using <code>name = value</code> formatting, but only when no explicit <code>-p/--print</code> arguments were supplied. Explicit <code>-p</code> arguments take precedence over this model-defined list.
			* If any <code>STUDY ... VARY ...</code> request is encountered during the run, the deferred no-<code>VARY</code> print action is suppressed for that run.

			Current output format is TSV.

			<span id="gtk-browser"></span>
			== GTK Browser ==

			In the GTK browser, <code>STUDY</code> uses the existing Observer and Study dialog workflow.

			* If no Observer exists yet, one is created.
			* The observed variables are added to the active Observer.
			* If <code>VARY</code> is omitted, the Observer is populated and no Study dialog is opened.
			* If <code>VARY</code> is present, the Study dialog is opened with the variable, bounds, stepping mode, distribution, and optional <code>RUN</code> method pre-populated.
			* If <code>VARY</code> is present and <code>NOW</code> is supplied, the pre-populated study is executed immediately without waiting for the user to press <code>OK</code>.
			* Solving then proceeds through the existing interactive Study dialog behavior.

			Current GTK limitation:

			* <code>FILE</code> is not yet implemented as an export path in the GTK browser. The GUI currently reports this and keeps the results in the Observer.

			Not yet implemented:

			* <code>ON_ERROR STOP \| SKIP \| CONTINUE</code>

			<span id="tcltk"></span>
			== Tcl/Tk ==

			The METHOD <code>STUDY</code> statement is currently not implemented in the Tcl/Tk GUI.

	[[Category:Syntax]]		[[Category:Syntax]]

Jpye: Created page with '{{missing}} Category:Syntax'

2010-05-17T03:10:51Z

Created page with '{{missing}} Category:Syntax'

New page

{{missing}}
[[Category:Syntax]]