External libraries - Revision history

Jpye: /* Freesteam */

2014-09-11T08:16:29Z

Freesteam

← Older revision		Revision as of 08:16, 11 September 2014
Line 172:		Line 172:
	The open source steam properties library '''freesteam''' (http://freesteam.sf.net) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.		The open source steam properties library '''freesteam''' (http://freesteam.sf.net) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.

	[[Image:Thermalequilibrium.png\|400px\|thumb\|none\|A transient simulation of the equilibrium of two masses of water, showing phase change. The steam properties are calculated using [http://freesteam.sf.net/ freesteam]. The integration was performed using [[IDA]]]].		[[Image:Thermalequilibrium.png\|400px\|thumb\|none\|A transient simulation of the equilibrium of two masses of water, showing phase change. The steam properties are calculated using [http://freesteam.sf.net/ freesteam]. The integration was performed using [[IDA]].]]

	[[Category:Documentation]]		[[Category:Documentation]]
	[[Category:Extending_ASCEND]]		[[Category:Extending_ASCEND]]
	[[Category:Development]]		[[Category:Development]]

Jpye: /* Freesteam */

2014-09-11T07:34:58Z

Freesteam

← Older revision		Revision as of 07:34, 11 September 2014
Line 172:		Line 172:
	The open source steam properties library '''freesteam''' (http://freesteam.sf.net) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.		The open source steam properties library '''freesteam''' (http://freesteam.sf.net) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.

	[[Image:Thermalequilibrium.png]]		[[Image:Thermalequilibrium.png\|400px\|thumb\|none\|A transient simulation of the equilibrium of two masses of water, showing phase change. The steam properties are calculated using [http://freesteam.sf.net/ freesteam]. The integration was performed using [[IDA]]]].
	A transient simulation of the equilibrium of two masses of water, showing phase change. The steam properties are calculated using [http://freesteam.sf.net/ freesteam]. The integration was performed using [[IDA]].

	[[Category:Documentation]]		[[Category:Documentation]]
	[[Category:Extending_ASCEND]]		[[Category:Extending_ASCEND]]
	[[Category:Development]]		[[Category:Development]]

Jpye: /* How external relations are used by ASCEND */

2013-03-07T05:51:55Z

How external relations are used by ASCEND

← Older revision		Revision as of 05:51, 7 March 2013
Line 67:		Line 67:
	When a black box is added your model, it creates a 'relation' object for each of your <tt>OUTPUT</tt> variables, and makes this relation incident with its output variable as well as with ''all'' of the <tt>INPUT</tt> variables for the black box:		When a black box is added your model, it creates a 'relation' object for each of your <tt>OUTPUT</tt> variables, and makes this relation incident with its output variable as well as with ''all'' of the <tt>INPUT</tt> variables for the black box:

	[[Image:Blackbox-incidence.png]]		[[Image:Blackbox-incidence.png\|thumb\|400px\|none\|Incidence matrix for a model containing a single 'black box' external relation containing 3 outputs and 9 inputs.]]
	Incidence matrix for a model containing a single 'black box' external relation containing 3 outputs and 9 inputs.

	When ASCEND reaches a block that contains external relations, it may find that all the INPUT variables are already known, in which case a single call the the external relation will be sufficient to determine the values of the OUTPUT variables. On the other hand, it may be that the values for some of the OUTPUT variables are already known (having been solved earlier in the solver process) and some of the INPUT variables are yet to be determined. In this case, ASCEND will use its standard Newton solver algorithm to home in on a solution for those variables. The external relation API provides the means for you to give a Jacobian matrix for the output variables relative to the input variables, which can then be used to improve the accuracy of the Newton solver. If you don't provide these derivatives, however, ASCEND will compute finite difference approximations by perturbing the values of the INPUT variables to estimate the Jacobian. Obviously this can result in many excess calls your your external relation evaluation function, so you will need to work out whether or not it is worth providing the derivative evaluation functions as well.		When ASCEND reaches a block that contains external relations, it may find that all the INPUT variables are already known, in which case a single call the the external relation will be sufficient to determine the values of the OUTPUT variables. On the other hand, it may be that the values for some of the OUTPUT variables are already known (having been solved earlier in the solver process) and some of the INPUT variables are yet to be determined. In this case, ASCEND will use its standard Newton solver algorithm to home in on a solution for those variables. The external relation API provides the means for you to give a Jacobian matrix for the output variables relative to the input variables, which can then be used to improve the accuracy of the Newton solver. If you don't provide these derivatives, however, ASCEND will compute finite difference approximations by perturbing the values of the INPUT variables to estimate the Jacobian. Obviously this can result in many excess calls your your external relation evaluation function, so you will need to work out whether or not it is worth providing the derivative evaluation functions as well.

Jpye: /* Freesteam */

2010-05-19T00:34:45Z

Freesteam

← Older revision		Revision as of 00:34, 19 May 2010
Line 171:		Line 171:
	== Freesteam ==		== Freesteam ==

	The open source steam properties library '''freesteam''' ([http://freesteam.sf.net]) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.		The open source steam properties library '''freesteam''' (http://freesteam.sf.net) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.

	[[Image:Thermalequilibrium.png]]		[[Image:Thermalequilibrium.png]]

Jpye: /* How external relations are used by ASCEND */

2010-05-19T00:34:15Z

How external relations are used by ASCEND

← Older revision		Revision as of 00:34, 19 May 2010
Line 64:		Line 64:

	External relations are solved to completion in the external code. When implementing your external relation, you should select your <tt>OUTPUT</tt> variables such that they can be calculated with certainty in terms of the <tt>INPUT</tt> and <tt>DATA</tt> variables. You can design your code to include its own internal iteration or solver procedure if necessary.		External relations are solved to completion in the external code. When implementing your external relation, you should select your <tt>OUTPUT</tt> variables such that they can be calculated with certainty in terms of the <tt>INPUT</tt> and <tt>DATA</tt> variables. You can design your code to include its own internal iteration or solver procedure if necessary.


	When a black box is added your model, it creates a 'relation' object for each of your <tt>OUTPUT</tt> variables, and makes this relation incident with its output variable as well as with ''all'' of the <tt>INPUT</tt> variables for the black box:		When a black box is added your model, it creates a 'relation' object for each of your <tt>OUTPUT</tt> variables, and makes this relation incident with its output variable as well as with ''all'' of the <tt>INPUT</tt> variables for the black box:

	~~<div class="thumb tnone"><div class="thumbinner" style="width:402px;">~~[[Image:Blackbox-incidence.png]] ~~<div class="thumbcaption"><div class="magnify">[[File:Blackbox-incidence.png\|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>~~Incidence matrix for a model containing a single 'black box' external relation containing 3 outputs and 9 inputs.~~</div></div></div>~~		[[Image:Blackbox-incidence.png]]
			Incidence matrix for a model containing a single 'black box' external relation containing 3 outputs and 9 inputs.

	When ASCEND reaches a block that contains external relations, it may find that all the INPUT variables are already known, in which case a single call the the external relation will be sufficient to determine the values of the OUTPUT variables. On the other hand, it may be that the values for some of the OUTPUT variables are already known (having been solved earlier in the solver process) and some of the INPUT variables are yet to be determined. In this case, ASCEND will use its standard Newton solver algorithm to home in on a solution for those variables. The external relation API provides the means for you to give a Jacobian matrix for the output variables relative to the input variables, which can then be used to improve the accuracy of the Newton solver. If you don't provide these derivatives, however, ASCEND will compute finite difference approximations by perturbing the values of the INPUT variables to estimate the Jacobian. Obviously this can result in many excess calls your your external relation evaluation function, so you will need to work out whether or not it is worth providing the derivative evaluation functions as well.		When ASCEND reaches a block that contains external relations, it may find that all the INPUT variables are already known, in which case a single call the the external relation will be sufficient to determine the values of the OUTPUT variables. On the other hand, it may be that the values for some of the OUTPUT variables are already known (having been solved earlier in the solver process) and some of the INPUT variables are yet to be determined. In this case, ASCEND will use its standard Newton solver algorithm to home in on a solution for those variables. The external relation API provides the means for you to give a Jacobian matrix for the output variables relative to the input variables, which can then be used to improve the accuracy of the Newton solver. If you don't provide these derivatives, however, ASCEND will compute finite difference approximations by perturbing the values of the INPUT variables to estimate the Jacobian. Obviously this can result in many excess calls your your external relation evaluation function, so you will need to work out whether or not it is worth providing the derivative evaluation functions as well.

Jpye at 00:33, 19 May 2010

2010-05-19T00:33:48Z

← Older revision		Revision as of 00:33, 19 May 2010
Line 7:		Line 7:
	* external import handlers (more on this later)		* external import handlers (more on this later)
	Currently all solvers and integrators for ASCEND are implemented as external libraries, as well as a number of external methods including a wrapper for [[QRSlv]] and a Brent solver for 'homing in' on a solution to a single variable in otherwise hard-to-solve cases. There are also external libraries for calculation of steam properties (see [http://freesteam.sf.net]), properties of other fluids (see [[FPROPS]]) and for modelling of heat transfer in long-pipe flow boiling (ask [[User:Jpye\|John Pye]]).		Currently all solvers and integrators for ASCEND are implemented as external libraries, as well as a number of external methods including a wrapper for [[QRSlv]] and a Brent solver for 'homing in' on a solution to a single variable in otherwise hard-to-solve cases. There are also external libraries for calculation of steam properties (see [http://freesteam.sf.net]), properties of other fluids (see [[FPROPS]]) and for modelling of heat transfer in long-pipe flow boiling (ask [[User:Jpye\|John Pye]]).


	Some other external libraries are under development including one for interpolating time-series data for use in simulations with forcing data.		Some other external libraries are under development including one for interpolating time-series data for use in simulations with forcing data.
Line 40:		Line 39:

	External relations are implemented as '''blocks''' of equations that are evaluated in external code. This means that you pass a set of 'input' variables, and the external code evaluates the resulting values of the 'output' variables. In addition, there is a provision for a 'data' object to be passed to the code. This data object should be constant-valued, so it can contain values that the external code won't be changing.		External relations are implemented as '''blocks''' of equations that are evaluated in external code. This means that you pass a set of 'input' variables, and the external code evaluates the resulting values of the 'output' variables. In addition, there is a provision for a 'data' object to be passed to the code. This data object should be constant-valued, so it can contain values that the external code won't be changing.


	To make use of an external relation (for example <tt>myextrel</tt> ) as declared in your library <tt>mylibrary</tt>, you use syntax like this:		To make use of an external relation (for example <tt>myextrel</tt> ) as declared in your library <tt>mylibrary</tt>, you use syntax like this:
Line 73:		Line 71:

	When ASCEND reaches a block that contains external relations, it may find that all the INPUT variables are already known, in which case a single call the the external relation will be sufficient to determine the values of the OUTPUT variables. On the other hand, it may be that the values for some of the OUTPUT variables are already known (having been solved earlier in the solver process) and some of the INPUT variables are yet to be determined. In this case, ASCEND will use its standard Newton solver algorithm to home in on a solution for those variables. The external relation API provides the means for you to give a Jacobian matrix for the output variables relative to the input variables, which can then be used to improve the accuracy of the Newton solver. If you don't provide these derivatives, however, ASCEND will compute finite difference approximations by perturbing the values of the INPUT variables to estimate the Jacobian. Obviously this can result in many excess calls your your external relation evaluation function, so you will need to work out whether or not it is worth providing the derivative evaluation functions as well.		When ASCEND reaches a block that contains external relations, it may find that all the INPUT variables are already known, in which case a single call the the external relation will be sufficient to determine the values of the OUTPUT variables. On the other hand, it may be that the values for some of the OUTPUT variables are already known (having been solved earlier in the solver process) and some of the INPUT variables are yet to be determined. In this case, ASCEND will use its standard Newton solver algorithm to home in on a solution for those variables. The external relation API provides the means for you to give a Jacobian matrix for the output variables relative to the input variables, which can then be used to improve the accuracy of the Newton solver. If you don't provide these derivatives, however, ASCEND will compute finite difference approximations by perturbing the values of the INPUT variables to estimate the Jacobian. Obviously this can result in many excess calls your your external relation evaluation function, so you will need to work out whether or not it is worth providing the derivative evaluation functions as well.


	=== DATA instance ===		=== DATA instance ===
Line 101:		Line 98:

	All ASCEND solvers are implemented as external libraries. This includes [[QRSlv]] as the default NLA solver, [[CONOPT]] as the standard optimisation solver, plus [[CMSlv]] as the conditional solver. See [[Solvers]] for more information.		All ASCEND solvers are implemented as external libraries. This includes [[QRSlv]] as the default NLA solver, [[CONOPT]] as the standard optimisation solver, plus [[CMSlv]] as the conditional solver. See [[Solvers]] for more information.


	Default solvers are loaded when ASCEND starts. To use other solvers, you must add an [[IMPORT]] statement at the start of your model file to trigger loading of the necessary shared library. Note the [[ASCENDSOLVERS]] environment variable can be used to located where these shared libraries are located, if necessary.		Default solvers are loaded when ASCEND starts. To use other solvers, you must add an [[IMPORT]] statement at the start of your model file to trigger loading of the necessary shared library. Note the [[ASCENDSOLVERS]] environment variable can be used to located where these shared libraries are located, if necessary.
Line 108:		Line 104:

	See also [[External Solvers]].		See also [[External Solvers]].



	== External integrators ==		== External integrators ==
Line 121:		Line 115:

	See also [[External Integrators]].		See also [[External Integrators]].


	== External import handlers ==		== External import handlers ==
Line 128:		Line 121:

	See also [[Import Handlers]].		See also [[Import Handlers]].



	== External CALLs ==		== External CALLs ==

	This seems to be a fossil in the code. There is some provision for 'CALL' statements that do something with external code. Not sure still what that does. This might be the start of a system for performing calls to functions '''with arguments''' from ASCEND METHODs, which is currently not implemented in general.		This seems to be a fossil in the code. There is some provision for 'CALL' statements that do something with external code. Not sure still what that does. This might be the start of a system for performing calls to functions '''with arguments''' from ASCEND METHODs, which is currently not implemented in general.


	== Writing an external library ==		== Writing an external library ==
Line 141:		Line 131:

	You will create a source code files <tt>extfn.c</tt> that will be complied into a shared library <tt>libextfn.so</tt> or a DLL <tt>extfn.dll</tt> depending on your platform.		You will create a source code files <tt>extfn.c</tt> that will be complied into a shared library <tt>libextfn.so</tt> or a DLL <tt>extfn.dll</tt> depending on your platform.


	Your source code needs file to contain a registration function named with the stem of the library name (<tt>extfn</tt>) with the added text <tt>_register</tt> added at the end. This will enable ASCEND to automatically discover the registration function for your external library.		Your source code needs file to contain a registration function named with the stem of the library name (<tt>extfn</tt>) with the added text <tt>_register</tt> added at the end. This will enable ASCEND to automatically discover the registration function for your external library.
Line 171:		Line 160:

	In order to compile your source code, you should use a SCons build file based on the example one given in <tt>models/johnpye/extfn</tt>. Note the useful <tt>ascend-config</tt> script that can help in determing your linker and compiler flags.		In order to compile your source code, you should use a SCons build file based on the example one given in <tt>models/johnpye/extfn</tt>. Note the useful <tt>ascend-config</tt> script that can help in determing your linker and compiler flags.


	Your sourcecode must contain (one or more functions like) the <tt>mylibrary_register</tt> that you referenced in your IMPORT statement. This function must contain one or more calls to <tt>CreateUserFunction</tt> which will tell ASCEND about the functions you are offering in your shared library.		Your sourcecode must contain (one or more functions like) the <tt>mylibrary_register</tt> that you referenced in your IMPORT statement. This function must contain one or more calls to <tt>CreateUserFunction</tt> which will tell ASCEND about the functions you are offering in your shared library.
Line 178:		Line 166:

	An important concept is the [[ImportHandler]]. This is a mechanism whereby you can define new types of external functionality to your model, to be accessed by the <tt>IMPORT</tt> statement. This means that the <tt>IMPORT</tt> statement is overloaded and can be set up to import anything you like, so long as ASCEND has been told how to deal with it.		An important concept is the [[ImportHandler]]. This is a mechanism whereby you can define new types of external functionality to your model, to be accessed by the <tt>IMPORT</tt> statement. This means that the <tt>IMPORT</tt> statement is overloaded and can be set up to import anything you like, so long as ASCEND has been told how to deal with it.


	See also [[Writing ASCEND external relations in C]].		See also [[Writing ASCEND external relations in C]].
Line 186:		Line 173:
	The open source steam properties library '''freesteam''' ([http://freesteam.sf.net]) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.		The open source steam properties library '''freesteam''' ([http://freesteam.sf.net]) includes bindings to ASCEND via the external 'black box' system. There is a windows installer. Once installed, you need to edit you <tt>.ascend.ini</tt> file so that the directory <tt>c:\Program Files\freesteam\ascend</tt> is included in your <tt>librarypath</tt>. Freesteam works equally well under Linux, although there are no binary packages at this stage.

			[[Image:Thermalequilibrium.png]]
	~~<div class="thumb tnone"><div class="thumbinner" style="width:502px;">~~[[Image:Thermalequilibrium.png]] ~~<div class="thumbcaption"><div class="magnify">[[File:Thermalequilibrium.png\|<img src="/skins/common/images/magnify-clip.png" width="15" height="11" alt="" />]]</div>~~A transient simulation of the equilibrium of two masses of water, showing phase change. The steam properties are calculated using [http://freesteam.sf.net/ freesteam]. The integration was performed using [[IDA]].~~</div></div></div>~~		A transient simulation of the equilibrium of two masses of water, showing phase change. The steam properties are calculated using [http://freesteam.sf.net/ freesteam]. The integration was performed using [[IDA]].



	[[Category:Documentation]]		[[Category:Documentation]]
	[[Category:Extending_ASCEND]]		[[Category:Extending_ASCEND]]
	[[Category:Development]]		[[Category:Development]]

Jpye: /* External methods */

2010-05-19T00:32:41Z

External methods

← Older revision		Revision as of 00:32, 19 May 2010
Line 14:		Line 14:

	== External methods ==		== External methods ==
	External methods can be used to implement procedural-style changes to your model via the [[EXTERNAL]] statement. This technique is used internally by ASCEND to implement the <tt>ClearAll</tt> method (see ~~<a href="https://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/~~models/basemodel.a4l~~?view=markup" class="external text" title="https://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/models/basemodel.a4l?view=markup" rel="nofollow">basemodel.a4l</a>~~. Here is the syntax to call an load and call an external method in a simple model:		External methods can be used to implement procedural-style changes to your model via the [[EXTERNAL]] statement. This technique is used internally by ASCEND to implement the <tt>ClearAll</tt> method (see {{src\|models/basemodel.a4l}}. Here is the syntax to call an load and call an external method in a simple model:

	<source lang="a4c">IMPORT "mylibrary"; (* load libmylibrary.so or mylibrary.dll *)		<source lang="a4c">IMPORT "mylibrary"; (* load libmylibrary.so or mylibrary.dll *)
Line 36:		Line 36:

	The [[IMPORT]] statement is used to specify how to load your external library; it is required that your external library contains a registration function that will tell ASCEND what external methods your library is providing.		The [[IMPORT]] statement is used to specify how to load your external library; it is required that your external library contains a registration function that will tell ASCEND what external methods your library is providing.


	== External relations (aka 'black box' relations) ==		== External relations (aka 'black box' relations) ==

Jpye at 01:32, 17 May 2010

2010-05-17T01:32:00Z

← Older revision		Revision as of 01:32, 17 May 2010
Line 16:		Line 16:
	External methods can be used to implement procedural-style changes to your model via the [[EXTERNAL]] statement. This technique is used internally by ASCEND to implement the <tt>ClearAll</tt> method (see <a href="https://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/models/basemodel.a4l?view=markup" class="external text" title="https://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/models/basemodel.a4l?view=markup" rel="nofollow">basemodel.a4l</a>. Here is the syntax to call an load and call an external method in a simple model:		External methods can be used to implement procedural-style changes to your model via the [[EXTERNAL]] statement. This technique is used internally by ASCEND to implement the <tt>ClearAll</tt> method (see <a href="https://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/models/basemodel.a4l?view=markup" class="external text" title="https://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/models/basemodel.a4l?view=markup" rel="nofollow">basemodel.a4l</a>. Here is the syntax to call an load and call an external method in a simple model:

	<source lang="a4c">IMPORT ~~"~~mylibrary~~"~~; (* load libmylibrary.so or mylibrary.dll *)		<source lang="a4c">IMPORT "mylibrary"; (* load libmylibrary.so or mylibrary.dll *)

	MODEL mymodel;		MODEL mymodel;
Line 45:		Line 45:
	To make use of an external relation (for example <tt>myextrel</tt> ) as declared in your library <tt>mylibrary</tt>, you use syntax like this:		To make use of an external relation (for example <tt>myextrel</tt> ) as declared in your library <tt>mylibrary</tt>, you use syntax like this:

	<source lang="a4c">IMPORT ~~"~~mylibrary~~"~~; (* ASCEND will try to load libmylibrary.so or mylibrary.dll depending your platform *)		<source lang="a4c">IMPORT "mylibrary"; (* ASCEND will try to load libmylibrary.so or mylibrary.dll depending your platform *)
	...		...

Line 90:		Line 90:
	These values can then be obtained in the external library code using (here C++) the following. The 'data' variable is passed in to the BBoxInitFn.		These values can then be obtained in the external library code using (here C++) the following. The 'data' variable is passed in to the BBoxInitFn.

	<source lang="c">symchar *myvalue_sym = AddSymbol(~~"~~myvalue~~"~~);		<source lang="c">symchar *myvalue_sym = AddSymbol("myvalue");
	struct Instance *myvalue_inst = ChildByChar(data,myvalue_sym);		struct Instance *myvalue_inst = ChildByChar(data,myvalue_sym);

	if(!myvalue_inst)throw runtime_error(~~"~~Instance 'myvalue' is required in DATA~~"~~);		if(!myvalue_inst)throw runtime_error("Instance 'myvalue' is required in DATA");
	double myvalue = RealAtomValue(myvalue_inst);</source>		double myvalue = RealAtomValue(myvalue_inst);</source>
	'''Note''' that this is intended to be a '''read-only''' mechanism; there is no guarantee, if you attempt to 'hold on' to pointers into this DATA instance, that those instances will still be there later on.		'''Note''' that this is intended to be a '''read-only''' mechanism; there is no guarantee, if you attempt to 'hold on' to pointers into this DATA instance, that those instances will still be there later on.
Line 116:		Line 116:
	Support for external ''integrators'' has also been implemented. This means that any new integrator your create can be loaded dynamically with the [[IMPORT]] statement. For example we provide [[DOPRI5]]:		Support for external ''integrators'' has also been implemented. This means that any new integrator your create can be loaded dynamically with the [[IMPORT]] statement. For example we provide [[DOPRI5]]:

	<source lang="a4c">IMPORT ~~"~~dopri5~~"~~;</source>		<source lang="a4c">IMPORT "dopri5";</source>

	For non-standard integrators, this additional IMPORT statement is required in order to for ASCEND to load the integrate. Standard integrators [[IDA]] and [[LSODE]] are always loaded, by default.		For non-standard integrators, this additional IMPORT statement is required in order to for ASCEND to load the integrate. Standard integrators [[IDA]] and [[LSODE]] are always loaded, by default.
Line 153:		Line 153:

	){		){
	const char *addone_help = ~~"~~This function will return one-plus-its-input-argument~~"~~;		const char *addone_help = "This function will return one-plus-its-input-argument";
	int result;		int result;

	result = CreateUserFunction(~~"~~add_one~~"~~		result = CreateUserFunction("add_one"
	,(ExtEvalFunc *)addone_prepare		,(ExtEvalFunc *)addone_prepare
	,(ExtEvalFunc **)addone_calc		,(ExtEvalFunc **)addone_calc

Jpye: /* DATA instance */

2010-05-17T01:31:17Z

DATA instance

← Older revision		Revision as of 01:31, 17 May 2010
Line 90:		Line 90:
	These values can then be obtained in the external library code using (here C++) the following. The 'data' variable is passed in to the BBoxInitFn.		These values can then be obtained in the external library code using (here C++) the following. The 'data' variable is passed in to the BBoxInitFn.

	<source lang="~~a4c~~">symchar *myvalue_sym = AddSymbol("myvalue");		<source lang="c">symchar *myvalue_sym = AddSymbol("myvalue");
	struct Instance *myvalue_inst = ChildByChar(data,myvalue_sym);		struct Instance *myvalue_inst = ChildByChar(data,myvalue_sym);

Line 98:		Line 98:

	See also [[Writing_ASCEND_external_relations_in_C\|a more detailed example]] about external relations.		See also [[Writing_ASCEND_external_relations_in_C\|a more detailed example]] about external relations.


	== External solvers ==		== External solvers ==

Jpye: /* Writing an external library */

2010-05-17T01:31:06Z

Writing an external library

← Older revision		Revision as of 01:31, 17 May 2010
Line 149:		Line 149:
	Your <tt>*_register</tt> function will in turn contain one or more calls to the ASCEND <tt>CreateUserFunction</tt> function. These calls will register your external methods and functions, allowing them to be called from your <tt>.a4c</tt> file. Here is an example of a registration function:		Your <tt>*_register</tt> function will in turn contain one or more calls to the ASCEND <tt>CreateUserFunction</tt> function. These calls will register your external methods and functions, allowing them to be called from your <tt>.a4c</tt> file. Here is an example of a registration function:

	<source lang="~~a4c~~">extern int		<source lang="c">extern int
	DLEXPORT mylibrary_register(struct Slv_Interp dummy1, struct Instance root		DLEXPORT mylibrary_register(struct Slv_Interp dummy1, struct Instance root
	,struct gl_list_t *arglist, unsigned long dummy4		,struct gl_list_t *arglist, unsigned long dummy4