Guidelines for model-writing - Revision history

Jpye: /* Avoid magic numbers */

2012-02-20T22:38:19Z

Avoid magic numbers

← Older revision		Revision as of 22:38, 20 February 2012
Line 44:		Line 44:
	For widely-used constants, such as <math>\pi</math> = 3.14159265358 or <math>g</math> = 9.81 m/s², you can use predefined values <tt>1{PI}</tt> and <tt>1{EARTH_G}</tt>, which are mostly defined in {{src\|models/measures.a4l}}. This makes your model more readable; the intention is clear, and ASCEND looks after the units for you as a bonus.		For widely-used constants, such as <math>\pi</math> = 3.14159265358 or <math>g</math> = 9.81 m/s², you can use predefined values <tt>1{PI}</tt> and <tt>1{EARTH_G}</tt>, which are mostly defined in {{src\|models/measures.a4l}}. This makes your model more readable; the intention is clear, and ASCEND looks after the units for you as a bonus.

	For constants that are important only in the context of a particular model, you can use types that are [[REFINES\|refinements]] of [[real_constant]], and then define your value in the model like this:		For constants that are important only in the context of a particular model, you can use types that are [[REFINES\|refinements]] of [[real_constant]] (declared using the [[CONSTANT]] statement), and then define your value in the model like this:
	<source lang=a4c>		<source lang=a4c>
	(* critical point temperature for water *)		(* critical point temperature for water *)

Jpye: /* Object-oriented naming */

2012-02-20T22:35:51Z

Object-oriented naming

← Older revision		Revision as of 22:35, 20 February 2012
Line 4:		Line 4:
	== Object-oriented naming ==		== Object-oriented naming ==

	Model names should be concise and represent ''things'' whereever possible, as opposed to ''processes'' or ''actions''. So, for example, you might write a model <tt>car_dynamic</tt> rather than a model <tt>acceleration_and_braking</tt>.		Model names should be concise and represent ''things'' whereever possible, as opposed to ''processes'' or ''actions'' or ''calculations''. So, for example, you might write a model <tt>car_dynamic</tt> rather than a model <tt>acceleration_and_braking</tt>.

	Note that if you have a model file "mymodel.a4c", then ''if'' it contains a model named "mymodel", that model will by default be instantiated when the model file is loaded. This is handy in many cases, because normally a model file with have a 'main purpose' that you mostly open it for. So use this default naming to make your model file easier to use.		Note that if you have a model file "mymodel.a4c", then ''if'' it contains a model named "mymodel", that model will by default be instantiated when the model file is loaded. This is handy in many cases, because normally a model file with have a 'main purpose' that you mostly open it for. So use this default naming to make your model file easier to use.

Jpye: /* Variable naming */

2012-02-20T22:35:04Z

Variable naming

← Older revision		Revision as of 22:35, 20 February 2012
Line 10:		Line 10:
	== Variable naming ==		== Variable naming ==

	ASCEND is essentially a mathematical modelling language. As equations quickly become complex, it is important that variables are named in a way that makes the resulting equations readable. It is preferable, therefore, to use standard abbreviations and symbols like <tt>h</tt> (for enthalpy) wherever possible, rather than the more typical computer-science approach of <tt>~~longVariableNamesDescribingWhatTheyAreFor~~</tt>.		ASCEND is essentially a mathematical modelling language. As equations quickly become complex, it is important that variables are named in a way that makes the resulting equations readable. It is preferable, therefore, to use standard abbreviations and symbols like <tt>h</tt> (for enthalpy) wherever possible, rather than the more typical computer-science approach of <tt>specificEnthalpyOfTheThingWeAreInterestedIn</tt>.

	Occasionally we come across cases where people from different backgrounds have different 'standard symbols'. In those cases, we tend to err towards the english/american standards from engineering textbooks. For energy systems modelling, textbooks like Holman, Cengel, and Moran & Shapiro give the general flavour.		Occasionally we come across cases where people from different backgrounds have different 'standard symbols'. In those cases, we tend to err towards the english/american standards from engineering textbooks. For energy systems modelling, textbooks like Holman, Cengel, and Moran & Shapiro give the general flavour.

Jpye at 06:21, 13 April 2011

2011-04-13T06:21:00Z

← Older revision		Revision as of 06:21, 13 April 2011
Line 82:		Line 82:

	Although you might be tempted to indent the [[METHODS]] and [[METHOD]] sections, it is our view that that leads to excessive indentation, without hugely increasing readability. If you use our [[syntax highlighting]] add-ins for various editors, the above syntax is usually quite readable.		Although you might be tempted to indent the [[METHODS]] and [[METHOD]] sections, it is our view that that leads to excessive indentation, without hugely increasing readability. If you use our [[syntax highlighting]] add-ins for various editors, the above syntax is usually quite readable.

			== Document your equations ==

			When writing models, it is a huge boost in re-usability if your model equations are clearly cited/sourced. The best way to do this is in comments near the equation, for example:

			<source lang=a4c>
			(* Following 3 eqns are from Potter & Wiggert, 3rd SI edition, sects 9.1, 9.2 and 9.4.*)
			S2.M^2 = ( S1.M^2 + 2/(k-1) ) / (2k/(k-1)S1.M^2 - 1);

			S2.p / S1.p = 2k/(k+1)S1.M^2 - (k-1)/(k+1);

			S2.T / S1.T = ( 1 + (k-1)/2S1.M^2) (2k/(k-1)S1.M^2 - 1)/ ((k+1)^2/2/(k-1)*S1.M^2);
			</source>

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

Jpye: /* Indenting */

2011-04-12T07:35:25Z

Indenting

← Older revision		Revision as of 07:35, 12 April 2011
Line 81:		Line 81:
	</source>		</source>

	Although you might be tempted to indent the [[METHODS]] and [[METHOD]] sections, it is our view that that leads to excessive indentation. If you use our [[syntax highlighting]] add-ins for various editors, the above syntax is usually quite readable.		Although you might be tempted to indent the [[METHODS]] and [[METHOD]] sections, it is our view that that leads to excessive indentation, without hugely increasing readability. If you use our [[syntax highlighting]] add-ins for various editors, the above syntax is usually quite readable.

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

Jpye at 07:34, 12 April 2011

2011-04-12T07:34:29Z

@@ Line 59: / Line 59: @@
 Nu = 0.023 * Re^(4./5) * Pr^n;
 </source>
 [[Category:Documentation]]

Jpye: /* Avoid magic numbers */

2011-04-12T01:39:44Z

Avoid magic numbers

← Older revision		Revision as of 01:39, 12 April 2011
Line 40:		Line 40:
	== Avoid magic numbers ==		== Avoid magic numbers ==

	In general, your equations should not contain an 'magic numbers'. This means values for which the source or meaning is not clear and not explained. Normally, such 'magic numbers' should be defined as constants, using a couple of possible approaches.		In general, your equations should not contain an 'magic numbers'. This means values for which the source or meaning is not clear and not explained. Such numbers make model files harder to maintain, as future user's won't know how to check whether a given value is correct, or what it means, or where it comes from. Normally, such 'magic numbers' should be defined as suitably-named constants, using a couple of possible approaches.

	For widely-used constants, such as <math>\pi</math> = 3.14159265358 or <math>g</math> = 9.81 m/s², you can use predefined values <tt>1{PI}</tt> and <tt>1{EARTH_G}</tt>, which are mostly defined in {{src\|models/measures.a4l}}. This makes your model more readable; the intention is clear, and ASCEND looks after the units for you as a bonus.		For widely-used constants, such as <math>\pi</math> = 3.14159265358 or <math>g</math> = 9.81 m/s², you can use predefined values <tt>1{PI}</tt> and <tt>1{EARTH_G}</tt>, which are mostly defined in {{src\|models/measures.a4l}}. This makes your model more readable; the intention is clear, and ASCEND looks after the units for you as a bonus.

Jpye: /* Avoid magic numbers */

2011-04-12T01:34:34Z

Avoid magic numbers

← Older revision		Revision as of 01:34, 12 April 2011
Line 40:		Line 40:
	== Avoid magic numbers ==		== Avoid magic numbers ==

	In general, your equations should not contain an 'magic numbers'. This means values for which the source or meaning is not clear and not explained. Normally, such 'magic numbers' should be defined as constants, such as <math>\pi</math> = 3.14159265358 ~~which should instead be written in ASCEND as <tt>1{PI}</tt>~~ or <math>g</math> = 9.81 m/s² ~~which~~ can ~~be written~~ <tt>1{EARTH_G}</tt>~~. These constants~~ are mostly defined in {{src\|models/measures.a4l}}. This ~~approach tends to be used in~~ ASCEND for ~~'universal' constants~~.		In general, your equations should not contain an 'magic numbers'. This means values for which the source or meaning is not clear and not explained. Normally, such 'magic numbers' should be defined as constants, using a couple of possible approaches.

			For widely-used constants, such as <math>\pi</math> = 3.14159265358 or <math>g</math> = 9.81 m/s², you can use predefined values <tt>1{PI}</tt> and <tt>1{EARTH_G}</tt>, which are mostly defined in {{src\|models/measures.a4l}}. This makes your model more readable; the intention is clear, and ASCEND looks after the units for you as a bonus.

	For constants that are important only in the context of a particular model, you can use types that are [[REFINES\|refinements]] of [[real_constant]], and then define your value in the model like this:		For constants that are important only in the context of a particular model, you can use types that are [[REFINES\|refinements]] of [[real_constant]], and then define your value in the model like this:
Line 48:		Line 50:
	T_c :== 647.096 {K};		T_c :== 647.096 {K};
	</source>		</source>
			The above approach is also useful for defining design parameters: they might be constant in the context of the problem that ASCEND is solving, but you might want to try running your model with different values to see what happens. In that case, you can change the values and re-run the model.

	One fair exception to the above 'rule' is that if you are citing an equation from a publication, and the equation is given in correct units-free form, then the dimensionless constants from that equation can be preserved in the ASCEND code. This applies, for example to many heat-transfer correlations, such as the [http://en.wikipedia.org/wiki/Nusselt_number#Dittus-Boelter_equation Dittus-Boelter correlation]], for example:		One fair exception to the above 'rule' is that if you are citing an equation from a publication, and the equation is given in correct units-free form, then the dimensionless constants from that equation can be preserved in the ASCEND code. This applies, for example to many heat-transfer correlations, such as the [http://en.wikipedia.org/wiki/Nusselt_number#Dittus-Boelter_equation Dittus-Boelter correlation]], for example:

Jpye at 01:31, 12 April 2011

2011-04-12T01:31:10Z

← Older revision		Revision as of 01:31, 12 April 2011
Line 38:		Line 38:
	Ideally, when a model file is loaded with the PyGTK GUI, it should immediately put itself into a solvable state. One should be able to load a model, click 'solve' and have some useful results. The power comes next, when the user can manually tweak the values of any variables in the model, to obtain results for new/different problems.		Ideally, when a model file is loaded with the PyGTK GUI, it should immediately put itself into a solvable state. One should be able to load a model, click 'solve' and have some useful results. The power comes next, when the user can manually tweak the values of any variables in the model, to obtain results for new/different problems.

	== Avoid 'magic numbers' ==		== Avoid magic numbers ==

	In general, your equations should not contain an 'magic numbers'. This means values for which the source or meaning is not clear and not explained. Normally, such 'magic numbers' should be defined as constants, such as <math>\pi</math> = 3.14159265358 which should instead be written in ASCEND as <tt>1{PI}</tt> or <math>g</math> = 9.81 m/s² which can be written <tt>1{EARTH_G}</tt>. These constants are mostly defined in {{src\|models/measures.a4l}}. This approach tends to be used in ASCEND for 'universal' constants.		In general, your equations should not contain an 'magic numbers'. This means values for which the source or meaning is not clear and not explained. Normally, such 'magic numbers' should be defined as constants, such as <math>\pi</math> = 3.14159265358 which should instead be written in ASCEND as <tt>1{PI}</tt> or <math>g</math> = 9.81 m/s² which can be written <tt>1{EARTH_G}</tt>. These constants are mostly defined in {{src\|models/measures.a4l}}. This approach tends to be used in ASCEND for 'universal' constants.

Jpye: /* Avoid 'magic numbers' */

2011-04-12T01:30:08Z

Avoid 'magic numbers'

← Older revision		Revision as of 01:30, 12 April 2011
Line 40:		Line 40:
	== Avoid 'magic numbers' ==		== Avoid 'magic numbers' ==

	In general, your equations should not contain an 'magic numbers'. This means values for which the source or meaning is not clear and not explained. Normally, such 'magic numbers' should be defined as constants, such as <math>\pi</math> = 3.14159265358 which should instead be written in ASCEND as <tt>1{PI}</tt> or <math>g</math> = 9.81 m/s² which can be written <tt>1{EARTH_G}</tt>. These constants are mostly defined in {{src\|models/~~atoms~~.a4l}}. This approach tends to be used in ASCEND for 'universal' constants.		In general, your equations should not contain an 'magic numbers'. This means values for which the source or meaning is not clear and not explained. Normally, such 'magic numbers' should be defined as constants, such as <math>\pi</math> = 3.14159265358 which should instead be written in ASCEND as <tt>1{PI}</tt> or <math>g</math> = 9.81 m/s² which can be written <tt>1{EARTH_G}</tt>. These constants are mostly defined in {{src\|models/measures.a4l}}. This approach tends to be used in ASCEND for 'universal' constants.

	For constants that are important only in the context of a particular model, you can use types that are [[REFINES\|refinements]] of [[real_constant]], and then define your value in the model like this:		For constants that are important only in the context of a particular model, you can use types that are [[REFINES\|refinements]] of [[real_constant]], and then define your value in the model like this: