Writing ASCEND external relations in C - Revision history

Jpye: /* Create an ASCEND wrapper library */

2026-03-06T11:15:02Z

Create an ASCEND wrapper library

← Older revision		Revision as of 11:15, 6 March 2026
Line 115:		Line 115:

	Note also that we are using the ERROR_REPORTER_HERE function (from compiler/error.h in libascend) to convey output back to ASCEND. This is much better than outputting to the console, as output via this function will be visible in the GUI, and it has 'status' associated with it too (e.g. ASC_PROG_NOTE is a 'note' for the user, and ASC_PROG_ERR is an error being reported, which would normally be shown in red).		Note also that we are using the ERROR_REPORTER_HERE function (from compiler/error.h in libascend) to convey output back to ASCEND. This is much better than outputting to the console, as output via this function will be visible in the GUI, and it has 'status' associated with it too (e.g. ASC_PROG_NOTE is a 'note' for the user, and ASC_PROG_ERR is an error being reported, which would normally be shown in red).

			<div style="solid 1pt blue">
			=== Note on “inputs” and “outputs” in CreateUserFunctionBlackBox ===

			The n_inputs and n_outputs values passed to CreateUserFunctionBlackBox(...) are the number of formal argument groups in the ASCEND statement, not necessarily the number of scalar
			real values that will be presented to the C evaluator.

			For example:

			<source lang=ascend>
			myrel: somefunc(
			T, P, n[1..10] : INPUT;
			H : OUTPUT;
			cfg : DATA
			);
			</source>

			has 3 formal inputs (T, P, n[1..10]) and 1 formal output (H), so the function should be registered with 3,1.

			During instantiation, ASCEND expands any array arguments into their scalar members and computes the actual flattened input/output vector lengths from that expanded argument list.
			Your prepare function can inspect this using the arglist, and your calc function will then receive the flattened scalar vectors.

			This distinction is important when designing external relations that accept array inputs: registration fixes the number of top-level argument groups, while instantiation determines
			the final scalar vector length actually passed to the blackbox.

			In practice, this means that array-valued inputs are already supported by the blackbox mechanism, provided ASCEND can expand them deterministically at instantiation time.
			</div>

	== Preparation and Calculation wrapper functions ==		== Preparation and Calculation wrapper functions ==

Jpye: /* Using it */

2026-03-06T11:11:27Z

Using it

← Older revision		Revision as of 11:11, 6 March 2026
Line 333:		Line 333:
	The other issue here is the [[IMPORT]] statement. This statement uses the ASCENDLIBRARY environment variable to hunt for your shared library before it attempts to import it. In this case, the 'mbwr' model has been created inside the standard ASCEND [[ModelLibrary]], so I didn't need to change the value of ASCENDLIBRARY. But sometimes you will need to do that before running ASCEND, eg:		The other issue here is the [[IMPORT]] statement. This statement uses the ASCENDLIBRARY environment variable to hunt for your shared library before it attempts to import it. In this case, the 'mbwr' model has been created inside the standard ASCEND [[ModelLibrary]], so I didn't need to change the value of ASCENDLIBRARY. But sometimes you will need to do that before running ASCEND, eg:

	<source lang="sh">export ASCENDLIBRARY=~/freesteam/ascend		<source lang="shellscript">export ASCENDLIBRARY=~/freesteam/ascend
	ascend testfreesteam.a4c</source>		ascend testfreesteam.a4c</source>

Jpye: /* Building and linking the code */

2026-03-06T11:11:10Z

Building and linking the code

← Older revision		Revision as of 11:11, 6 March 2026
Line 274:		Line 274:
	Providing ASCEND has been installed on your system (Note: including 'devel' files, if you're installing from an RPM package or Windows installer), you should now be able to just run SCons to build the shared library, like so:		Providing ASCEND has been installed on your system (Note: including 'devel' files, if you're installing from an RPM package or Windows installer), you should now be able to just run SCons to build the shared library, like so:

	<source lang="sh">john@thunder:~/ascend/models/johnpye/fprops$ scons		<source lang="shellscript">john@thunder:~/ascend/models/johnpye/fprops$ scons
	scons: Reading SConscript files ...		scons: Reading SConscript files ...
	scons: done reading SConscript files.		scons: done reading SConscript files.

Jpye: /* Building and linking the code */

2026-03-06T11:10:57Z

Building and linking the code

← Older revision		Revision as of 11:10, 6 March 2026
Line 261:		Line 261:
	At this point we have two files, <tt>mbwr.c</tt> (containing the code-to-be-wrapped) and <tt>asc_mbwr.c</tt> (the ASCEND wrapper code for our function). To build the shared library, we add the following <tt>SConstruct</tt> file that will make use of [http://www.scons.org SCons] to generate a shared library for ASCEND on our system. The only requirement is that the program 'ascend-config' should already be on our PATH, which might require some tweaking in the case of Windows.		At this point we have two files, <tt>mbwr.c</tt> (containing the code-to-be-wrapped) and <tt>asc_mbwr.c</tt> (the ASCEND wrapper code for our function). To build the shared library, we add the following <tt>SConstruct</tt> file that will make use of [http://www.scons.org SCons] to generate a shared library for ASCEND on our system. The only requirement is that the program 'ascend-config' should already be on our PATH, which might require some tweaking in the case of Windows.

	<source lang="py">env = Environment()		<source lang="python">env = Environment()

	# get compiler and linker flags for libascend		# get compiler and linker flags for libascend

Jpye: sp

2018-01-03T23:14:02Z

← Older revision		Revision as of 23:14, 3 January 2018
Line 1:		Line 1:
	This HOWTO will guide you through the steps required to access [[External_relations\|external relation]] code for ASCEND from the [http://en.wikipedia.org/wiki/C_(programming_language) C language]. As an example, we will walk through the implementation of an external thermodynamic properties correlation using the modified Benedict-Webb-Rubin correlation, with the added benefit of a useful and reasonably well-documented piece of code. For a little more background on these so-called 'black box' external relations, see the PhD thesis of Kirk ~~Abbot~~ (in [[Publications]]).		This HOWTO will guide you through the steps required to access [[External_relations\|external relation]] code for ASCEND from the [http://en.wikipedia.org/wiki/C_(programming_language) C language]. As an example, we will walk through the implementation of an external thermodynamic properties correlation using the modified Benedict-Webb-Rubin correlation, with the added benefit of a useful and reasonably well-documented piece of code. For a little more background on these so-called 'black box' external relations, see the PhD thesis of Kirk Abbott (in [[Publications]]).

	All the code associated with this HOWTO (and possibly a bit more, over time) is available from {{srcdir\|models/johnpye/fprops/}} in the [[ModelLibrary]],		All the code associated with this HOWTO (and possibly a bit more, over time) is available from {{srcdir\|models/johnpye/fprops/}} in the [[ModelLibrary]],

Jpye: mention Kirk

2018-01-03T23:13:38Z

mention Kirk

← Older revision		Revision as of 23:13, 3 January 2018
Line 1:		Line 1:
	This HOWTO will guide you through the steps required to access [[External_relations\|external relation]] code for ASCEND from the [http://en.wikipedia.org/wiki/C_(programming_language) C language]. As an example, we will walk through the implementation of an external thermodynamic properties correlation using the modified Benedict-Webb-Rubin correlation, with the added benefit of a useful and reasonably well-documented piece of code.		This HOWTO will guide you through the steps required to access [[External_relations\|external relation]] code for ASCEND from the [http://en.wikipedia.org/wiki/C_(programming_language) C language]. As an example, we will walk through the implementation of an external thermodynamic properties correlation using the modified Benedict-Webb-Rubin correlation, with the added benefit of a useful and reasonably well-documented piece of code. For a little more background on these so-called 'black box' external relations, see the PhD thesis of Kirk Abbot (in [[Publications]]).

	All the code associated with this HOWTO (and possibly a bit more, over time) is available from {{srcdir\|models/johnpye/fprops/}} in the [[ModelLibrary]],		All the code associated with this HOWTO (and possibly a bit more, over time) is available from {{srcdir\|models/johnpye/fprops/}} in the [[ModelLibrary]],

Jpye: /* References */

2012-10-02T03:14:26Z

References

← Older revision		Revision as of 03:14, 2 October 2012
Line 361:		Line 361:

	== References ==		== References ==

			<references/>

	[[Category:Documentation]]		[[Category:Documentation]]

Jpye: /* Decide on the C functions that you want to access */

2012-10-02T03:13:47Z

Decide on the C functions that you want to access

← Older revision		Revision as of 03:13, 2 October 2012
Line 6:		Line 6:
	Firstly, you need to provide the C code for the functions that you want to be able to access from ASCEND. In this HOWTO, we're interested in '''external relations''', which means equations or functions that we want to be able to use from within an ASCEND model. The most typical application of external relations is probably thermodynamic property correlations, but other examples include pressure-drop correlations (e.g. pipe friction), and perhaps getting data from lookup tables, etc.		Firstly, you need to provide the C code for the functions that you want to be able to access from ASCEND. In this HOWTO, we're interested in '''external relations''', which means equations or functions that we want to be able to use from within an ASCEND model. The most typical application of external relations is probably thermodynamic property correlations, but other examples include pressure-drop correlations (e.g. pipe friction), and perhaps getting data from lookup tables, etc.

	In this case, we want to access the Modified Benedict-Webb-Rubin (MBWR) thermodynamic property correlation for the refrigerant '''R123'''. The MBWR correlation data for this refrigerant was published in 1994 by Younglove, and McLinden<~~sup id="_ref-0" class="reference"~~>~~<a href="#_note-0" title="">[~~1]</a></~~sup~~>. We have implemented a function which provides the general form of an MBWR correlation as follows, with the intention that our fluid-specific correlation data would also be passed in to the function as a pointer to a <tt>MbwrData</tt> struct:		In this case, we want to access the Modified Benedict-Webb-Rubin (MBWR) thermodynamic property correlation for the refrigerant '''R123'''. The MBWR correlation data for this refrigerant was published in 1994 by Younglove, and McLinden<ref>B A Younglove and M O McLinden, 1994, An International Standard Equation of State for the Thermodynamic Properties of Refrigerant 123 (2,2‐Dichloro‐1,1,1‐Trifluoroethane), J. Phys. Chem. Ref. Data '''23''' p.731, {{doi\|10.1063/1.555950}}</ref>. We have implemented a function which provides the general form of an MBWR correlation as follows, with the intention that our fluid-specific correlation data would also be passed in to the function as a pointer to a <tt>MbwrData</tt> struct:
	<source lang="c">/* from mbwr.h: */		<source lang="c">/* from mbwr.h: */
	typedef struct MbwrData_struct{		typedef struct MbwrData_struct{

Jpye at 23:55, 25 May 2010

2010-05-25T23:55:50Z

Show changes

Jpye: /* Preparation and Calculation wrapper functions */

2010-05-25T23:51:26Z

Preparation and Calculation wrapper functions

← Older revision		Revision as of 23:51, 25 May 2010
Line 136:		Line 136:


	<source lang="~~a4c~~">myprops: mbwr_p(		<source lang="c">myprops: mbwr_p(
	T, rhob : INPUT;		T, rhob : INPUT;

Line 148:		Line 148:
	The 'prepare' function has the following structure:		The 'prepare' function has the following structure:

	<source lang="~~a4c~~">int mbwr_p_prepare(struct BBoxInterp *bbox,		<source lang="c">int mbwr_p_prepare(struct BBoxInterp *bbox,
	struct Instance *data,		struct Instance *data,

Line 167:		Line 167:
	Our 'mbwr_p_prepare' function therefore contains the following code, which looks for a member called 'component' inside the DATA instance, and asserts that its value be equal to "R123", because we've only implemented support for this one fluid so far.		Our 'mbwr_p_prepare' function therefore contains the following code, which looks for a member called 'component' inside the DATA instance, and asserts that its value be equal to "R123", because we've only implemented support for this one fluid so far.

	<source lang="~~a4c~~">int mbwr_p_prepare(struct BBoxInterp *bbox,		<source lang="c">int mbwr_p_prepare(struct BBoxInterp *bbox,
	struct Instance *data,		struct Instance *data,

Line 217:		Line 217:
	The 'calculate' function is where ASCEND instructs our external relation to actually be evaluated. This is the part that gets called over and over again during ASCEND's solver iterations, so it's written for efficient access to the values that need to be used. The structure of the 'calculate' function is as follows:		The 'calculate' function is where ASCEND instructs our external relation to actually be evaluated. This is the part that gets called over and over again during ASCEND's solver iterations, so it's written for efficient access to the values that need to be used. The structure of the 'calculate' function is as follows:

	<source lang="~~a4c~~">int mbwr_p_calc(struct BBoxInterp *bbox,		<source lang="c">int mbwr_p_calc(struct BBoxInterp *bbox,
	int ninputs, int noutputs,		int ninputs, int noutputs,

Line 230:		Line 230:


	<source lang="~~a4c~~">int mbwr_p_calc(struct BBoxInterp *bbox,		<source lang="c">int mbwr_p_calc(struct BBoxInterp *bbox,
	int ninputs, int noutputs,		int ninputs, int noutputs,

Line 260:		Line 260:

	If it is possible that your external function may return error codes, you have the opportunity of passing those errors back to ASCEND, or alternatively you can choose to ignore the errors. In many cases Newton iteration will work best if you can evaluate smooth curves even outside their 'acceptable range', and not return errors when values are outside those ranges.		If it is possible that your external function may return error codes, you have the opportunity of passing those errors back to ASCEND, or alternatively you can choose to ignore the errors. In many cases Newton iteration will work best if you can evaluate smooth curves even outside their 'acceptable range', and not return errors when values are outside those ranges.


	== Building and linking the code ==		== Building and linking the code ==