C Plus Plus Tutorial

From assela Pathirana

Jump to: navigation, search

Computer Science is no more about computers than astronomy is about telescopes. -- Edsger Dijkstra

For the SUIS Coding Boot Camp on C++ conducted by Assela Pathirana

ATTENTION
These pages are designed to be read online. Please DO NOT print them. If you need a copy, just save this page to your computer, so that you can read it while off-line.

Contents


Introduction

This tutorial is designed for you to learn the C/C++ language in a rapid-phased way, generally over a period of four days of intense work. Even though you will have some time with an instructor, you will have to do a lot of practice as homework in order to gain sufficient confidence as a programmer. Most of the material is ideal for self-study.

Acknowledgment

A number of sections of this tutorial were adopted with permission from Juan Soulie's excellent C++ Language Tutorial published in cplusplus.com. In many of the lessons, changes from original tutorial are minor. However, there are some important differences in a few sections. Therefore, you are advised to follow the present tutorial during the course. On the other hand, remember that Juan Soulie's site will hopefully be updated more frequently, therefore for general look-up for help, that site will be better.

My colleague Billah helped to convert the original tutorial to this format. Thanks, Billah.

How to use this material effectively

It is important to keep in mind that C++ and Visual C++ 2005 Express Edition are not the same thing. C++ is the language. Visual C++ 2005 Express Edition is the compiler used to build a program with that language. There are many other alternatives to Visual C++ 2005 Express Edition as compilers. These can do the task of compiling a C++ program equally well.

Let's face it, our mission here is not to become professional programmers. The objective is rather to become familiar with programming as a tool. Think of programming as a challenge similar to learn cycling. You need some instructions and perhaps a bit of 'pep-talk', but what is mostly needed is to go out there and do it! And then practice a lot. It may be not possible for everybody to become a racing cyclist, but anyone can learn how to ride a bike for leisure or commuting. In my decade-long experience in teaching programming as a useful tool, I never came across someone who could not master it with adequate practice.

I will help you to set up a environment where you can write and test programs. There are many good compilers out there for C++ and some of the best ones are free and open source. However, the platform we use to try-out these examples is Visual C++ 2005 Express Edition which is a free version of a commercial software. Please keep in mind that there are many other ways of doing the same thing.

If you want to install and configure Visual C++ 2005 Express Edition yourself, please follow the instructions given in this page.

Some platform related stuff

Visual C++ 2005 Express Edition manages its files organized into 'Projects' and 'Solutions'. A 'Solution' can have several 'Projects' under it. This creates a multitude of files, that has nothing to do with C++, but just to help Visual C++ 2005 Express Edition to do the housekeeping. In the beginning, this can lead to confusion.

I have prepared a template project that you can download and extract in your working computer. Using this project will make your life much easier. Download it from here and unzip it in an empty directory. Then clicking on file cbcpp.sln should open the solution and project in Visual C++ 2005 Express Edition. The file structure will be something like the following:

 
├───myprograms
│   ├───lesson1
│   ├───lesson2
│   └───lesson3
└───vsee2005stuff
    │   cbcpp.ncb
    │   cbcpp.sln
    │   cbcpp.vcproj
    │
    └───Debug
            BuildLog.htm
            cbcpp.ilk
            cbcpp.pdb
            mt.dep
            ptr2.obj
            vc80.idb
            vc80.pdb

All the files in the folder vsee2005stuff and its sub-folders are not important for our learning tasks. Following figure shows the Visual C++ 2005 Express Edition environment with this project (and solution) open.

File:Vcppee2005.ep.jpg

In order to compile and run a program, you should write it in this environment (We will come to that in the next chapter.) This can be done by right-clicking on source files, then Add, New Item. You will get a dialog like the following.

File:Vcppee2005.ep2.jpg

Remember two things here:

  • Save your source code as *.cc or *.cpp (e.g. hello.cc or hello.cpp) (Name box)
  • In the Location box navigate to a sub-folder in myprograms (e.g. myprograms\lesson1. This will keep your code neatly sepearted from Visual C++ 2005 Express Edition related stuff.

Template:Cpptutorial Structure of a program Template:Cpptutorial Variables. Data Types.

Constants

Constants are expressions with a fixed value.

Literals

Literals are used to express particular values within the source code of a program. We have already used these previously to give concrete values to variables or to express messages we wanted our programs to print out, for example, when we wrote:

a = 5;

the 5 in this piece of code was a literal constant.

Literal constants can be divided in Integer Numerals, Floating-Point Numerals, Characters, Strings and Boolean Values.

Integer Numerals

1776
707
-273

They are numerical constants that identify integer decimal values. Notice that to express a numerical constant we do not have to write quotes (") nor any special character. There is no doubt that it is a constant: whenever we write 1776 in a program, we will be referring to the value 1776.

In addition to decimal numbers (those that all of us are used to use every day) C++ allows the use as literal constants of octal numbers (base 8) and hexadecimal numbers (base 16). If we want to express an octal number we have to precede it with a (zero character). And in order to express a hexadecimal number we have to precede it with the characters 0x (zero, x). For example, the following literal constants are all equivalent to each other:

75         // decimal

0113       // octal
0x4b       // hexadecimal

All of these represent the same number: 75 (seventy-five) expressed as a base-10 numeral, octal numeral and hexadecimal numeral, respectively.

Literal constants, like variables, are considered to have a specific data type. By default, integer literals are of type int. However, we can force them to either be unsigned by appending the u character to it, or long by appending l:

75         // int

75u        // unsigned int
75l        // long
75ul       // unsigned long

In both cases, the suffix can be specified using either upper or lowercase letters.

Floating Point Numbers

They express numbers with decimals and/or exponents. They can include either a decimal point, an e character (that expresses "by ten at the Xth height", where X is an integer value that follows the e character), or both a decimal point and an e character:

3.14159    // 3.14159

6.02e23    // 6.02 x 1023
1.6e-19    // 1.6 x 10-19
3.0        // 3.0

These are four valid numbers with decimals expressed in C++. The first number is PI, the second one is the number of Avogadro, the third is the electric charge of an electron (an extremely small number) -all of them approximated- and the last one is the number three expressed as a floating-point numeric literal.

The default type for floating point literals is double. If you explicitly want to express a float or long double numerical literal, you can use the f or l suffixes respectively:

3.14159L   // long double

6.02e23f   // float

Any of the letters than can be part of a floating-point numerical constant (e, f, l) can be written using either lower or uppercase letters without any difference in their meanings.

Character and string literals

There also exist non-numerical constants, like:

'z'
'p'

"Hello world"
"How do you do?"

The first two expressions represent single character constants, and the following two represent string literals composed of several characters. Notice that to represent a single character we enclose it between single quotes (') and to express a string (which generally consists of more than one character) we enclose it between double quotes (").

When writing both single character and string literals, it is necessary to put the quotation marks surrounding them to distinguish them from possible variable identifiers or reserved keywords. Notice the difference between these two expressions:

x
'x'

x alone would refer to a variable whose identifier is x, whereas 'x' (enclosed within single quotation marks) would refer to the character constant 'x'.

Character and string literals have certain peculiarities, like the escape codes. These are special characters that are difficult or impossible to express otherwise in the source code of a program, like newline (\n) or tab (\t). All of them are preceded by a backslash (\). Here you have a list of some of such escape codes:

\n newline
\r carriage return
\t tab
\v vertical tab
\b backspace
\f form feed (page feed)
\a alert (beep)
\' single quote (')
\" double quote (")
\? question mark (?)
\\ backslash (\)

For example:

'\n'
'\t'
"Left \t Right"
"one\ntwo\nthree"

Additionally, you can express any character by its numerical ASCII code by writing a backslash character (\) followed by the ASCII code expressed as an octal (base-8) or hexadecimal (base-16) number. In the first case (octal) the digits must immediately follow the backslash (for example \23 or \40), in the second case (hexadecimal), an x character must be written before the digits themselves (for example \x20 or \x4A).

String literals can extend to more than a single line of code by putting a backslash sign (\) at the end of each unfinished line.

"string expressed in \
two lines" 

You can also concatenate several string constants separating them by one or several blank spaces, tabulators, newline or any other valid blank character:

"this forms" "a single" "string" "of characters"

Finally, if we want the string literal to be explicitly made of wide characters (wchar_t), instead of narrow characters (char), we can precede the constant with the L prefix:

L"This is a wide character string"

Wide characters are used mainly to represent non-English or exotic character sets.

Boolean literals

In C++, true and false are represented by 1 (non-zero) and 0, respectively.

There are only two valid Boolean values: true and false. These can be expressed in C++ as values of type bool by using the Boolean literals true and false.

Defined constants (#define)

You can define your own names for constants that you use very often without having to resort to memory-consuming variables, simply by using the #define preprocessor directive. Its format is:

#define identifier value

For example:

#define PI 3.14159265

#define NEWLINE '\n'

This defines two new constants: PI and NEWLINE. Once they are defined, you can use them in the rest of the code as if they were any other regular constant, for example:

// defined constants: calculate circumference

#include <iostream>
using namespace std;


#define PI 3.14159
#define NEWLINE '\n'

int main ()
{
  double r=5.0;               // radius
  double circle;

  circle = 2 * PI * r;
  cout << circle;
  cout << NEWLINE;

  return 0;
}

31.4159

In fact the only thing that the compiler preprocessor does when it encounters #define directives is to literally replace any occurrence of their identifier (in the previous example, these were PI and NEWLINE) by the code to which they have been defined (3.14159265 and '\n' respectively).

Remember NOT TO end #define directives with a semicolon. If you do, you will get very strange errors.

The #define directive is not a C++ statement but a directive for the preprocessor; therefore it assumes the entire line as the directive and does not require a semicolon (;) at its end. If you append a semicolon character (;) at the end, it will also be appended in all occurrences within the body of the program that the preprocessor replaces.

Declared constants (const)

With the const prefix you can declare constants with a specific type in the same way as you would do with a variable:

const int pathwidth = 100;
const char tabulator = '\t';
 const zipcode = 12440;

In case that no type is explicitly specified (as in the last example) the compiler assumes that it is of type int.

Operators

Once we know of the existence of variables and constants, we can begin to operate with them. For that purpose, C++ integrates operators. Unlike other languages whose operators are mainly keywords, operators in C++ are mostly made of signs that are not part of the alphabet but are available in all keyboards. This makes C++ code shorter and more international, since it relies less on English words, but requires a little of learning effort in the beginning.

You do not have to memorize all the content of this page. Most details are only provided to serve as a later reference in case you need it.

Assignment (=)

The assignment operator assigns a value to a variable.

a = 5;

This statement assigns the integer value 5 to the variable a. The part at the left of the assignment operator (=) is known as the lvalue (left value) and the right one as the rvalue (right value). The lvalue has to be a variable whereas the rvalue can be either a constant, a variable, the result of an operation or any combination of these.
The most important rule when assigning is the right-to-left rule: The assignment operation always takes place from right to left, and never the other way:

a = b;

This statement assigns to variable a (the lvalue) the value contained in variable b (the rvalue). The value that was stored until this moment in a is not considered at all in this operation, and in fact that value is lost.

Consider also that we are only assigning the value of b to a at the moment of the assignment operation. Therefore a later change of b will not affect the new value of a.

For example, let us have a look at the following code - I have included the evolution of the content stored in the variables as comments:

// assignment operator

#include <iostream>
using namespace std;

int main ()
{
  int a, b;         // a:?,  b:?

  a = 10;           // a:10, b:?
  b = 4;            // a:10, b:4
  a = b;            // a:4,  b:4
  b = 7;            // a:4,  b:7

  cout << "a:";
   cout << a;
   cout << " b:";
   cout << b;
 
   return 0;
}
a:4 b:7

This code will give us as result that the value contained in a is 4 and the one contained in b is 7. Notice how a was not affected by the final modification of b, even though we declared a = b earlier (that is because of the right-to-left rule).

A property that C++ has over other programming languages is that the assignment operation can be used as the rvalue (or part of an rvalue) for another assignment operation. For example:

Writing code like
a=2+(b=5);
works, but poor style. Write two statements:

b=5; a=2+b;

, instead.
a = 2 + (b = 5);

is equivalent to:

b = 5;
a = 2 + b;

that means: first assign 5 to variable b and then assign to a the value 2 plus the result of the previous assignment of b (i.e. 5), leaving a with a final value of 7.

The following expression is also valid in C++:

a = b = c = 5;

It assigns 5 to the all the three variables: a, b and c.

Arithmetic operators ( +, -, *, /, % )

The five arithmetical operations supported by the C++ language are:

+ addition
- subtraction
* multiplication
/ division
 % modulo

Operations of addition, subtraction, multiplication and division literally correspond with their respective mathematical operators. The only one that you might not be so used to see may be modulo; whose operator is the percentage sign (%). Modulo is the operation that gives the remainder of a division of two values. For example, if we write:

a = 11 % 3;

the variable a will contain the value 2, since 2 is the remainder from dividing 11 between 3.

Compound assignment (+=, -=, *=, /=, %=, >>=, <<=, &=, ^=, |=)

When we want to modify the value of a variable by performing an operation on the value currently stored in that variable we can use compound assignment operators:

expression is equivalent to
value += increase; value = value + increase;
a -= 5; a = a - 5;
a /= b; a = a / b;
price *= units + 1; price = price * (units + 1);

and the same for all other operators. For example:

// compound assignment operators

#include <iostream>
using namespace std;

int main ()
{
  int a, b=3;
  a = b;
  a+=2;             // equivalent to a=a+2

  cout << a;
  return 0;
}
5

Increase and decrease (++, --)

Shortening even more some expressions, the increase operator (++) and the decrease operator (--) increase or reduce by one the value stored in a variable. They are equivalent to +=1 and to -=1, respectively. Thus:

c++;
c+=1;
c=c+1;

are all equivalent in its functionality: the three of them increase by one the value of c.

In the early C compilers, the three previous expressions probably produced different executable code depending on which one was used. Nowadays, this type of code optimization is generally done automatically by the compiler, thus the three expressions should produce exactly the same executable code.

A characteristic of this operator is that it can be used both as a prefix and as a suffix. That means that it can be written either before the variable identifier (++a) or after it (a++). Although in simple expressions like a++ or ++a both have exactly the same meaning, in other expressions in which the result of the increase or decrease operation is evaluated as a value in an outer expression they may have an important difference in their meaning: In the case that the increase operator is used as a prefix (++a) the value is increased before the result of the expression is evaluated and therefore the increased value is considered in the outer expression; in case that it is used as a suffix (a++) the value stored in a is increased after being evaluated and therefore the value stored before the increase operation is evaluated in the outer expression. Notice the difference:

Example 1 Example 2
B=3;
A=++B;
// A contains 4, B contains 4
B=3;
A=B++;
// A contains 3, B contains 4

In Example 1, B is increased before its value is copied to A. While in Example 2, the value of B is copied to A and then B is increased.

Relational and equality operators ( ==, !=, >, <, >=, <= )

In order to evaluate a comparison between two expressions we can use the relational and equality operators. The result of a relational operation is a Boolean value that can only be true or false, according to its Boolean result.

We may want to compare two expressions, for example, to know if they are equal or if one is greater than the other is. Here is a list of the relational and equality operators that can be used in C++:

In C++ = and == are not the same thing! a=b, assigns the value of b to a, while a==b tests whether a and b are equal! Remember this to avoid very nasty errors.

== Equal to
!= Not equal to
> Greater than
< Less than
>= Greater than or equal to
<= Less than or equal to

Here there are some examples:

(7 == 5)     // evaluates to false.

(5 > 4)      // evaluates to true.
(3 != 2)     // evaluates to true.
(6 >= 6)     // evaluates to true.
(5 < 5)      // evaluates to false.

Of course, instead of using only numeric constants, we can use any valid expression, including variables. Suppose that a=2, b=3 and c=6,

(a == 5)     // evaluates to false since a is not equal to 5.
(a*b >= c)   // evaluates to true since (2*3 >= 6) is true. 
(b+4 > a*c)  // evaluates to false since (3+4 > 2*6) is false. 

((b=2) == a) // evaluates to true. 

Be careful! The operator = (one equal sign) is not the same as the operator == (two equal signs), the first one is an assignment operator (assigns the value at its right to the variable at its left) and the other one (==) is the equality operator that compares whether both expressions in the two sides of it are equal to each other. Thus, in the last expression ((b=2) == a), we first assigned the value 2 to b and then we compared it to a, that also stores the value 2, so the result of the operation is true.

Logical operators ( !, &&, || )

The Operator ! is the C++ operator to perform the Boolean operation NOT, it has only one operand, located at its right, and the only thing that it does is to inverse the value of it, producing false if its operand is true and true if its operand is false. Basically, it returns the opposite Boolean value of evaluating its operand. For example:

!(5 == 5)    // evaluates to false because the expression at its right (5 == 5) is true. 
 
 !(6 <= 4)    // evaluates to true because (6 <= 4) would be false. 
 !true        // evaluates to false
 !false       // evaluates to true. 

The logical operators && and || are used when evaluating two expressions to obtain a single relational result. The operator && corresponds with Boolean logical operation AND. This operation results true if both its two operands are true, and false otherwise. The following panel shows the result of operator && evaluating the expression a && b:

&& OPERATOR

a b a && b
true true true
true false false
false true false
false false false

The operator || corresponds with Boolean logical operation OR. This operation results true if either one of its two operands is true, thus being false only when both operands are false themselves. Here are the possible results of a || b:

|| OPERATOR

a b a b
true true true
true false true
false true true
false false false

For example:

( (5 == 5) && (3 > 6) )  // evaluates to false ( true && false ).

( (5 == 5) || (3 > 6) )  // evaluates to true ( true || false ).

Conditional operator ( ? )

The conditional operator evaluates an expression returning a value if that expression is true and a different one if the expression is evaluated as false. Its format is:

condition ? result1 : result2

If condition is true the expression will return result1, if it is not it will return result2.

7==5 ? 4 : 3     // returns 3, since 7 is not equal to 5.

7==5+2 ? 4 : 3   // returns 4, since 7 is equal to 5+2.
5>3 ? a : b      // returns the value of a, since 5 is greater than 3.
a>b ? a : b      // returns whichever is greater, a or b.
// conditional operator

#include <iostream>

using namespace std;

int main ()
{
  int a,b,c;

  a=2;
  b=7;
  c = (a>b) ? a : b;

  cout << c;

  return 0;
}

7

In this example a was 2 and b was 7, so the expression being evaluated (a>b) was not true, thus the first value specified after the question mark was discarded in favor of the second value (the one after the colon) which was b, with a value of 7.

Comma operator ( , )

The comma operator (,) is used to separate two or more expressions that are included where only one expression is expected. When the set of expressions has to be evaluated for a value, only the rightmost expression is considered.

For example, the following code:

a = (b=3, b+2);

Would first assign the value 3 to b, and then assign b+2 to variable a. So, at the end, variable a would contain the value 5 while variable b would contain value 3.

Bitwise Operators ( &, |, ^, ~, <<, >> )

Bitwise operators modify variables considering the bit patterns that represent the values they store.

operator asm equivalent description
& AND Bitwise AND
| OR Bitwise Inclusive OR
^ XOR Bitwise Exclusive OR
~ NOT Unary complement (bit inversion)
<< SHL Shift Left
>> SHR Shift Right

Explicit type casting operator

Type casting operators allow you to convert a datum of a given type to another. There are several ways to do this in C++. The simplest one, which has been inherited from the C language, is to precede the expression to be converted by the new type enclosed between parentheses (()):

int i;
float f = 3.14;
i = (int) f;

The previous code converts the float number 3.14 to an integer value (3), the remainder is lost. Here, the typecasting operator was (int). Another way to do the same thing in C++ is using the functional notation: preceding the expression to be converted by the type and enclosing the expression between parentheses:

i = int ( f );

Both ways of type casting are valid in C++.

sizeof()

This operator accepts one parameter, which can be either a type or a variable itself and returns the size in bytes of that type or object:

a = sizeof (char);

This will assign the value 1 to a because char is a one-byte long type.
The value returned by sizeof is a constant, so it is always determined before program execution.

Other operators

Later in these tutorials, we will see a few more operators, like the ones referring to pointers or the specifics for object-oriented programming. Each one is treated in its respective section.

Precedence of operators

Do not rely on intricate rules of precedence to write complicated expressions. Instead always use parenthesis. It make your code easy to maintain, read and less error prone.

When writing complex expressions with several operands, we may have some doubts about which operand is evaluated first and which later. For example, in this expression:

a = 5 + 7 % 2

we may doubt if it really means:

a = 5 + (7 % 2)    // with a result of 6, or
a = (5 + 7) % 2    // with a result of 0

The correct answer is the first of the two expressions, with a result of 6. If you are interested in finding how this happend and to get a thorough idea on the precedence of operators read this page. However, give everybody (including you) a break -- use parenthesis and do not depend too much on these rules!! Template:Cpptutorial Basic Input/Output Template:Cpptutorial Control Structures Template:Cpptutorial Functions (I) Template:Cpptutorial Functions (II)

Arrays and Vectors

When you write new code in C++, use Vectors instead of arrays. Almost always they are easier to work with.

In old C the way to store a number of values of same type (say integers) is to use an Array -- which can be thought of as a line of slots that we can fill in with values. In general arrays should have fixed size that is determined during the compile time (there are ways to avoid this problem!). C++ has Vectors -- array's on steroids -- think of these as expandable bags. You can load them with any number of values as you like! If you write code in C++, you can get away without using Arrays at all. But, in old code written in C, arrays appear quite often. So, we shall cover arrays first.

Arrays

An array is a series of elements of the same type placed in contiguous memory locations that can be individually referenced by adding an index to a unique identifier.

That means that, for example, we can store 5 values of type int in an array without having to declare 5 different variables, each one with a different identifier. Instead of that, using an array we can store 5 different values of the same type, int for example, with a unique identifier.

For example, an array to contain 5 integer values of type int called billy could be represented like this:

File:9-imgarra1.gif

where each blank panel represents an element of the array, that in this case are integer values of type int. These elements are numbered from to 4 since in arrays the first index is always , independently of its length.

Like a regular variable, an array must be declared before it is used. A typical declaration for an array in C++ is:

type name [elements];

where type is a valid type (like int, float...), name is a valid identifier and the elements field (which is always enclosed in square brackets []), specifies how many of these elements the array has to contain.

Therefore, in order to declare an array called billy as the one shown in the above diagram it is as simple as:

int billy [5];

NOTE: The elements field within brackets [] which represents the number of elements the array is going to hold, must be a constant value, since arrays are blocks of non-dynamic memory whose size must be determined before execution. In order to create arrays with a variable length dynamic memory is needed, which is explained later in these tutorials.

Initializing arrays.

When declaring a regular array of local scope (within a function, for example), if we do not specify otherwise, its elements will not be initialized to any value by default, so their content will be undetermined until we store some value in them. The elements of global and static arrays, on the other hand, are automatically initialized with their default values, which for all fundamental types this means they are filled with zeros.

In both cases, local and global, when we declare an array, we have the possibility to assign initial values to each one of its elements by enclosing the values in braces { }. For example:

int billy [5] = { 16, 2, 77, 40, 12071 }; 

This declaration would have created an array like this:

File:9-imgarra3.gif

The amount of values between braces { } must not be larger than the number of elements that we declare for the array between square brackets [ ]. For example, in the example of array billy we have declared that it has 5 elements and in the list of initial values within braces { } we have specified 5 values, one for each element.

When an initialization of values is provided for an array, C++ allows the possibility of leaving the square brackets empty [ ]. In this case, the compiler will assume a size for the array that matches the number of values included between braces { }:

int billy [] = { 16, 2, 77, 40, 12071 };

After this declaration, array billy would be 5 ints long, since we have provided 5 initialization values.

Accessing the values of an array.

In any point of a program in which an array is visible, we can access the value of any of its elements individually as if it was a normal variable, thus being able to both read and modify its value. The format is as simple as:

name[index]

Following the previous examples in which billy had 5 elements and each of those elements was of type int, the name which we can use to refer to each element is the following:

File:9-imgarra2.gif

For example, to store the value 75 in the third element of billy, we could write the following statement:

billy[2] = 75;

and, for example, to pass the value of the third element of billy to a variable called a, we could write:

a = billy[2];

Therefore, the expression billy[2] is for all purposes like a variable of type int.

Notice that the third element of billy is specified billy[2], since the first one is billy[0], the second one is billy[1], and therefore, the third one is billy[2]. By this same reason, its last element is billy[4]. Therefore, if we write billy[5], we would be accessing the sixth element of billy and therefore exceeding the size of the array.

In C++ it is syntactically correct to exceed the valid range of indices for an array. This can create problems, since accessing out-of-range elements do not cause compilation errors but can cause runtime errors. The reason why this is allowed will be seen further ahead when we begin to use pointers.

At this point it is important to be able to clearly distinguish between the two uses that brackets [ ] have related to arrays. They perform two different tasks: one is to specify the size of arrays when they are declared; and the second one is to specify indices for concrete array elements. Do not confuse these two possible uses of brackets [ ] with arrays.

int billy[5];         // declaration of a new array

billy[2] = 75;        // access to an element of the array.

If you read carefully, you will see that a type specifier always precedes a variable or array declaration, while it never precedes an access.

Some other valid operations with arrays:

billy[0] = a;
billy[a] = 75;
b = billy [a+2];
billy[billy[a]] = billy[2] + 5;
// arrays example
#include <iostream>
using namespace std;

int billy [] = {16, 2, 77, 40, 12071};

int n, result=0;

int main ()
{
  for ( n=0 ; n<5 ; n++ )
  {
    result += billy[n];
  }
  cout << result;
  return 0;
}
12206

Multidimensional arrays

Multidimensional arrays can be described as "arrays of arrays". For example, a bidimensional array can be imagined as a bidimensional table made of elements, all of them of a same uniform data type.

File:9-imgarra5.gif

jimmy represents a bidimensional array of 3 per 5 elements of type int. The way to declare this array in C++ would be:

int jimmy [3][5];

and, for example, the way to reference the second element vertically and fourth horizontally in an expression would be:

jimmy[1][3]

File:9-imgarra6.gif

(remember that array indices always begin by zero).

Multidimensional arrays are not limited to two indices (i.e., two dimensions). They can contain as many indices as needed. But be careful! The amount of memory needed for an array rapidly increases with each dimension. For example:

char century [100][365][24][60][60];

declares an array with a char element for each second in a century, that is more than 3 billion chars. So this declaration would consume more than 3 gigabytes of memory!

Arrays as parameters

At some moment we may need to pass an array to a function as a parameter. In C++ it is not possible to pass a complete block of memory by value as a parameter to a function, but we are allowed to pass its address. In practice this has almost the same effect and it is a much faster and more efficient operation.

In order to accept arrays as parameters the only thing that we have to do when declaring the function is to specify in its parameters the element type of the array, an identifier and a pair of void brackets []. For example, the following function:

void procedure (int arg[])

accepts a parameter of type "array of int" called arg. In order to pass to this function an array declared as:

int myarray [40];

it would be enough to write a call like this:

procedure (myarray);

Here you have a complete example:

// arrays as parameters
#include <iostream>
using namespace std;


void printarray (int arg[], int length) {
  for (int n=0; n<length; n++)
    cout << arg[n] << " ";
   cout << "\n";
 }
 
 
 int main ()
{
  int firstarray[] = {5, 10, 15};
  int secondarray[] = {2, 4, 6, 8, 10};
  printarray (firstarray,3);
  printarray (secondarray,5);
  return 0;
}
5 10 15
2 4 6 8 10

As you can see, the first parameter (int arg[]) accepts any array whose elements are of type int, whatever its length. For that reason we have included a second parameter that tells the function the length of each array that we pass to it as its first parameter. This allows the for loop that prints out the array to know the range to iterate in the passed array without going out of range.

In a function declaration it is also possible to include multidimensional arrays. The format for a tridimensional array parameter is:

base_type[][depth][depth]

for example, a function with a multidimensional array as argument could be:

void procedure (int myarray[][3][4])

Notice that the first brackets [] are left blank while the following ones are not. This is so because the compiler must be able to determine within the function which is the depth of each additional dimension.

Arrays, both simple or multidimensional, passed as function parameters are a quite common source of errors for novice programmers. I recommend the reading of the chapter about Pointers for a better understanding on how arrays operate.

Vectors -- Arrays made easy

Arrays are simple as long as their dimensions are fixed. What if the size of the array is determined by the data? While there are ways to overcome this issue, they tend to be somewhat complicated. An alternative is to use the vector structure that is available in C++. Vectors are way easier to use than traditional arrays. Let's start with an example.

/** Vector demonstration I
**/
#include <vector>
#include <iostream>
#include <string>
using namespace std;
 
int main ()
{
	vector<string> animals;
	do{
		string animal;
		cout << "An animal (Just Enter to end):";
		getline(cin, animal);
		if(animal==""){
			break;
		}
		animals.push_back(animal);
	}while(true);
	cout << "I got the following:\n";
	for(unsigned int i=0;i<animals.size();i++){
		cout << animals[i]<<'\n';
	}
 
}
An animal (Just Enter to end):rabbit
An animal (Just Enter to end):fox
An animal (Just Enter to end):chicken
An animal (Just Enter to end):
I got the following:
rabbit
fox
chicken

Almost always, vectors are better substitutes for arrays. Learn to use them effectively. However, one situation where you may have to use arrays is when dealing with C language (prior to C++) code libraries.

Let's go through this code:

#include <vector>
directive needed (to include vector headers) if you want to use vectors.
vector<string> animals;
animals is a vector, with string elements. (You can define vectors with any type of elements. e.g. vector<int> age;.
animals.push_back(animal);
add the string stored in animal variable to animals vector. (Vector will grow by one element.)
animals.size()
The size of the vector. (i.e. number of elements.)
animals[i]
Elements of vectors can be accessed using the same notation that we use for arrays. (Alternatively you can use animals.at(i).)

Vectors of Vectors

It is possible to define vectors of vectors (of vectors ...) as follows.

vector < vector <int> > matrix; //defines a vector of vector of integers.

Following is an example of vector of vectors in use.

/* vectors of vectors */
#include <vector>
#include <iostream>
#include <sstream>
using namespace std;
 
int main ()
{
	vector < vector <double> > matrix; //matrix is a vector of, vector of doubles.
	vector <double> line;              //line is a vector of doubles
	matrix.push_back(line);			   //add a 'line' to the 'matrix'
	cout << "Enter your matrix. One number at a time.\n";
	cout << "'Enter' to break current line.\n";
	cout << "x'Enter' to end entering.\n";
 
	int i=0,j=0;
	while(true){
		string mystr;
		getline (cin,mystr); //read what was entered. 
		if(mystr==""){       // if it is blank (just Enter)
			j++;                   // increase the row count. 
			matrix.push_back(line);// add a row to the matrix.
			cout << "Enter next row.\n";
			continue;	     // no need to waste time, start next iteration. 
		}
		if(mystr=="x"){	     // if it is "x"
			break;           // we are out!
		}
		// now we assume its a number. 
		//In reality we need a bit of error handling.
		//But let's keep things simple here. 
		double tmp;
		stringstream(mystr) >> tmp; //convert mystr to a double and store in tmp
		matrix[j].push_back(tmp);   //add that double (tmp) to row j of matrix.
	}
	cout << "Done entering!\n You entered the following matrix.\n";
	for (unsigned int j=0;j<matrix.size();j++){// for each row in matrix
		for(unsigned int i=0;i<matrix[j].size();i++){// for each place in jth row.
			cout << matrix[j][i] <<'\t';
		}
		cout << '\n';
	}
}

A typical run of this program would look like the following:

 
Enter your matrix. One number at a time.
'Enter' to break current line.
x'Enter' to end entering.
2
3

Enter next row.
4
5
6
7
8
9

Enter next row.
1

Enter next row.
25
26
x
Done entering!
 You entered the following matrix.
2       3
4       5       6       7       8       9
1
25      26

Vectors running wild!

If you reuse a vector, first you need to explicitly remove all stuff. Remember to empty your bags before refilling them!

Think of vectors as bags of unlimited space. They are very convenient because you don't have to know what is the number of items you are going to fill them with in advance, they just keep on growing!! However, this same property can lead to problems if you don't pay attention. One of the common mistakes made by new programmers is forgetting to empty the vector (bag) before putting new set of items (refilling the bag!).

Lets suppose you write a program where you use an array/a vector to store a number of items. Let's say, within the program you do it several times. In arrays when you do the following:

 
int vals[5];
...
vals[i]=5;

we explicitly say replace the slot number i of vals with value 5. But in vectors

vector <int> vals;
...
vals.push_back(5);

what we say is add the value 5 to the bag vals. Notice that if we don't need the old values, we have to explicitly erase them!

You can erase a whole vector by

vals.erase();

Template:Cpptutorial Character Sequences

Pointers

The concept of pointers in a simple one; however, in old C language the pointers are perhaps the single most common cause of program failure in code written by novice programmers. A good way to start, eh? Well.. pointers can be trouble makers, but the good news is, unlike in C, with C++ there many ways to avoid using them. Before we go any further, the rule of the game of pointers (at least for the 'rest of us') is don't use them unless absolutely necessary.

Having said that, using 'Pointers' for essential tasks is not difficult, and the rules that govern how they work are pretty simple. The rules can be combined to get complex results, but the individual rules remain simple.

Before we go any further, lets define what a `pointer' is.

Pointer
A pointer is a programming language data type whose value refers directly to (or “points to”) another value stored elsewhere in the computer memory using its address.

A good analogy is the relationship between a web page and its URL (address). For example http://en.wikipedia.org/wiki/Banana is URL of the page describing Bananas on Wikipedia. If we know the above address it allows us to reach the Banana Page. However, http://en.wikipedia.org/wiki/Banana is not the Banana Page, but only the address of that page.

Similarly a pointer in computer jargon is a reference (or address) of something.

Pointers and Pointees

Remember this: Addresses are pointers. The stuff referred to by those addresses (Banana Page in case of http://en.wikipedia.org/wiki/Banana or your home, in case of your postal address.) is pointee.

In C/C++ we denote this as follows:

/* Pointer/ Pointee demo */
#include<iostream>
using namespace std;
int main(){
	int *k; // the pointee of k is an integer. 
	int y;  // y is an integer
	y=0;    // set y to zero
	k=&y;   // point k to the address of y (y is pointee of k now)
	*k=40;  // set the value of pointee of k (ah, ha!) to 40. 
	cout << y <<"\n"; // print y. 
	cout << (*k) <<"\n"; // print pointee of k
}

The notation * can be read as pointee of and & as address of.

What k=&y; *k=40; does is equivalent of y=40 in a very round about way!! This code shows one of the major issues of pointer usage. Where there are pointers -- there are hidden links. If we don't keep a track of these links, we are inviting for trouble!

If you are interested in a more in-depth coverage of the pointers in general make a detour to this link. The rest of this article covers only two important aspects of pointers.

Using Pointers to get values out of functions

The most straight forward way to get the results of a function is its return value. If you need to get several values out of a function how do you do that? One way is to use Data Structures, a topic we are yet to cover. Another is to use pointers. See the following example:

#include <iostream>
using namespace std;
void add(int *a){ // pointee of a is an integer
	(*a)+=5;		  // add 5 to pointee of a
}
 
int main ()
{
	int val=0;      // val is zero
        int *k;  // k's pointee is an integer. 
	k=&val;  //now k points to the address of val
	add(k);      // pass k, i.e. address of val
	cout << val;    // val has changed! 
}

The following section is a formal explanation of what is happening.

Passing by value or by reference

All the simple functions we have seen in section Functions and thereafter, the arguments passed to the functions have been passed by value. This means that when calling a function with parameters, what we have passed to the function were copies of their values but never the variables themselves. For example in the followng code

// function example
#include <iostream>
using namespace std;
 
 
int addition (int a, int b)
{
  int r;
  r=a+b;
  return (r);
}
 
int main ()
{
  int z;
  z = addition (5,3);
  cout << "The result is " << z;
  return 0;
}

What we did in this case was to call to function addition passing the values of x and y, i.e. 5 and 3 respectively, but not the variables x and y themselves.

File:8-imgfunc1.gif

This way, when the function addition is called, the value of its local variables a and b become 5 and 3 respectively, but any modification to either a or b within the function addition will not have any effect in the values of x and y outside it, because variables x and y were not themselves passed to the function, but only copies of their values at the moment the function was called.

But there might be some cases where you need to manipulate from inside a function the value of an external variable. For that purpose we can use arguments passed by reference, as in the function duplicate of the following example:

// passing parameters by reference

#include <iostream>
using namespace std;

void duplicate (int& a, int& b, int& c)
{
  a*=2;
  b*=2;
  c*=2;
}


int main ()
{
  int x=1, y=3, z=7;
  duplicate (x, y, z);
  cout << "x=" << x << ", y=" << y << ", z=" << z;
  return 0;
}

x=2, y=6, z=14

The first thing that should call your attention is that in the declaration of duplicate the type of each parameter was followed by an ampersand sign (&). This ampersand is what specifies that their corresponding arguments are to be passed by reference instead of by value.

When a variable is passed by reference we are not passing a copy of its value, but we are somehow passing the variable itself to the function and any modification that we do to the local variables will have an effect in their counterpart variables passed as arguments in the call to the function.

File:8-imgfunc3.gif

To explain it in another way, we associate a, b and c with the arguments passed on the function call (x, y and z) and any change that we do on a within the function will affect the value of x outside it. Any change that we do on b will affect y, and the same with c and z.

That is why our program's output, that shows the values stored in x, y and z after the call to duplicate, shows the values of all the three variables of main doubled.

If when declaring the following function:

void duplicate (int& a, int& b, int& c)

we had declared it this way:

void duplicate (int a, int b, int c)

i.e., without the ampersand signs (&), we would have not passed the variables by reference, but a copy of their values instead, and therefore, the output on screen of our program would have been the values of x, y and z without having been modified.

Passing by reference is also an effective way to allow a function to return more than one value. For example, here is a function that returns the previous and next numbers of the first parameter passed.

// more than one returning value

#include <iostream>
using namespace std;

void prevnext (int x, int& prev, int& next)
{
  prev = x-1;
  next = x+1;
}


int main ()
{
  int x=100, y, z;
  prevnext (x, y, z);
  cout << "Previous=" << y << ", Next=" << z;
  return 0;
}

Previous=99, Next=101

Passing functions as pointers

Note
This section can be skipped without much harm!

We can pass whole functions as arguments to other functions using pointers. See the following example.

#include <iostream>
using namespace std;
int oper(int one, int two, int (*myfunc)(int,int)){ // pointee of myfunc is a function 
						    //and takes two integer arguments
						    // and return an integer. 
	return (*myfunc)(one,two);		    // &x - 'pointer of x is..'
						    // *x - 'pointee of x is..'
 
}
 
int bigger(int a, int b){
	if(a>b){
		return a;
	}else{
		return b;
	}
}
 
int smaller(int a, int b){
	if(a>b){
		return b;
	}else{
		return a;
	}
}
 
int main ()
{
	int a=5, b=10;
	cout << oper(a,b,&bigger)<<'\n';
	cout << oper(a,b,&smaller)<<'\n';
}

Template:Cpptutorial Data Structures Template:Cpptutorial Input/Output with files

Writing Good Code

Keeping things organized

Putting it all together -- Optimization and EPAnet

This section contains some advanced stuff. Don't be discouraged if you don't understand all and difficult to complete it without the help of somebody else.

Prerequisites

  1. You should have completed the C++ programming primer preceeding this section.
  2. You have exposure to the EPAnet 2 software (graphical version is adequate).
  3. A basic understanding of Genetic Algorithms (Follow these links: [1],[2],[3] and spend some time if not.)

In this lesson, we push the abilities we have gained to the limit! We link two code libraries, namely, Evolving objects -- a versatile genetic algorithm code and EPAnet (toolkit) a pipe network calculation model by writing some relatively simple code and create a running program. The following section explains the problem we have selected to solve (please note that the problem itself is of secondary importance here, what we are trying to do is to hone the skills we have gained and build confidence to attack bigger coding projects).

You can download the set of files needed for this exercise from : File:Cbcpp EO.rar.

Problem

The problem network.

The figure on the left shows a water supply network with a reservoir, seven pipe segments conveying water and five junctions that have different demands. We want to compute the most economical pipe diameters for each segment while maintaining a minimum pressure head of 10 m at all junctions. You can open the File:Cbcpp pipe network1.inp in Epanet 2 software to view the network.

Our plan is to use a Genetic Algorithm to optimize the pipe diameters. For this we need to connect Epanet Software to a genetic algorithm code.

Plan

We will use the Epanet Toolkit, a programming interface designed to run Epanet 2.0 programmatically without the standard graphical interface. For the Genetic Algorithm part, we'll use Evolving objects a free and open source package for evolutionary computations.

Evolving objects can be downloaded from eodev] website. Epanet toolkit can be downloaded from [US-EPA]. However, for this exercise you may use the already downloaded versions of these tools. Download the file File:Cbcpp EO.zip into your computer and extract it to a new folder (say E:\GA\EO). This will create four subfolders,

code
data
eo-1.0
epanet_tools

We use code folder to keep all the code we write (not the code libraries we use!). It already have the files:

RealEA.cpp
real_value.h

RealEA.cpp is a c++ program that can be used to access the EO Genetic algorithm functions. real_value.h has the cost function for the GA. We'll learn more about this later.

data folder where we shall keep all our data, has the water distribution network file.

eo-1.0 and epanet_tools have the evolving objects and epanet toolkit code libraries.

Solution

We shall attack our problem in a piecemeal fashion, in the steps given below:

  1. Get EO to solve a small GA problem.
  2. Replace the cost function with our own.
  3. Use epanet_toolkit to run Epanet on our water supply network and use the results to evaluate a cost function.

Usually this step-by-step approach is less error-prone than attempting the whole task once.

Running a GA

Create a new folder called projects under the same folder that has sub-folders of code, data, etc. This is where we shall keep the visual studio express edition related (platform specific) stuff. Open visual C++ and reate a new empty project EPGA in that folder. Add the following files in the code folder to the project.

 
RealEA.cpp
real_value.h

When you try to compile the project, you will get the error message on the line:

#include <eo>

Indicating that the compiler can not include 'eo'. To remedy this, we should include the path to the include file eo ("..\..\eo-1.0.1\src"). This can be done by additing it to: Edit-><project>Properties->C/C++->General->Additional include directories.

At this stage RealEA.cpp should comile successfully, but would cause errors at linking stage. The error messages would look like

unresolved external symbol "public: virtual __thiscall eoFunctorStore::~eoFunctorStore(void)" 
(??1eoFunctorStore@@UAE@XZ) referenced in function 
"public: virtual void * __thiscall eoFunctorStore::`scalar deleting destructor'(unsigned int)" 
(??_GeoFunctorStore@@UAEPAXI@Z)

The reason for this is

  1. The compiler knows about eo library (by #include <eo>), but
  2. the real library objects of eo needed for linking are missing

To rectify this, we should let the linker access to the necessary libraries. Before doing this we have to make a detour. First save your project/solution and close it.

Building EO libraries

The eo code available for download does not have the libraries for windows built in, but they have the complete source and tools needed to build them. There is a visual C++ solution called eo.sln in the sub-folder win. Just build this solution (Project->Build solution). This will create the necessary libraries in the win.

One more point: It is beneficial to build the release version (not the debug version) of the libraries for performance reasons.

After this you will have the following libraries in the folder win\lib\release.

eo.lib  eoes.lib  eoga.lib  eoutils.lib
Adding linker dependancies.

Now open your project again. In add the above four files as dependancies for the linker. (Edit-><project>Properties->Linker->General->Additional Dependancies).

Then let the linker know where these are: (Edit-><project>Properties->Linker->General->Additional Library Directories). Add something like ..\..\eo-1.0.1\win\lib\release.

At this stage, you should be able to compile the project successfully. Debug->Start without Debugging should run the program, albeit with not-so-meaningful-at-the-moment results.


Enable debugging

If you try to debug your code at this stage, visual c++ 2005 will complain (as of 01:07, 9 April 2007 (JST)) that the binaries were not built with debug information. There is a separate article on how to enable debugging in visual studio 2005.

EO In-Action

Now is a good time to have an idea about how our GA code works. Don't worry if you can not understand everything -- what is important is to have a general idea of how things work!

The actual code-in-action is very short, indeed. I have changed the comments a little bit.

  /* Many instructions to this program can be given on the command line. 
     The following code understands what you have specified as command line arguments. 
  */
  eoParser parser(argc, argv);  // for user-parameter reading
  eoState state;    // keeps all things allocated
 
  typedef eoReal<eoMinimizingFitness> EOT;
 
  // The evaluation fn - encapsulated into an eval counter for output 
  eoEvalFuncPtr<EOT, double, const std::vector<double>&> 
               mainEval( real_value );
  eoEvalFuncCounter<EOT> eval(mainEval);
  // the genotype - through a genotype initializer
  eoRealInitBounded<EOT>& init = make_genotype(parser, state, EOT());
  // Build the variation operator (any seq/prop construct)
  eoGenOp<EOT>& op = make_op(parser, state, init);
  // initialize the population - and evaluate
  // yes, this is representation indepedent once you have an eoInit
  eoPop<EOT>& pop   = make_pop(parser, state, init);
  // stopping criteria
  eoContinue<EOT> & term = make_continue(parser, state, eval);
  // output
  eoCheckPoint<EOT> & checkpoint = make_checkpoint(parser, state, eval, term);
  // algorithm (need the operator!)
  eoAlgo<EOT>& ea = make_algo_scalar(parser, state, eval, checkpoint, op);
  make_help(parser); //print help, if something is missing or user gives /h 
  // evaluate intial population AFTER help and status in case it takes time
  apply<EOT>(eval, pop);
  // print it out
  cout << "Initial Population\n";
  pop.sortedPrintOn(cout);
  cout << endl;
 
  run_ea(ea, pop); // run the ea
 
  cout << "Final Population\n";
  pop.sortedPrintOn(cout);
  cout << endl;

You can get away without understanding a single line of code above!! The only critical part is the following function, specified in the header file real_value.h. In order to adopt these versatile algorithms to solve a problem of our choosing, only changing this header file is adequate.

Fitness function

double real_value(const std::vector<double>& _ind)
{
  double sum = 0;
  for (unsigned i = 0; i < _ind.size(); i++)
      sum += _ind[i] * _ind[i];
  return sqrt(sum);
}

The eo library expects this function to be present and uses to evaluate the individuals in the population for fitness.

What happens here?

  1. Our genotype vector has (say) n number of items. The fitness function simply squares each of these and add them up and returns the square root. No rocket science here! Just, the rule here is larger the individuals -- better the fitness!!
  2. The GA code does the rest,

Try running the algorithm. It will go on decreasing the cost function and exit at 100th generation. The default is 100 generations, in a moment, we'll get into the details on how to change the default behavior.

Providing arguments

Once you run the above code once successfully, check the folder that consists the executable file (project\EPGA\Debug folder). There should be a file EPGA.exe.status EO library creates this file, when you run the program. It lists all the changes you can make at the runtime to the GA. (Meaning, you don't have to recompile the program -- just indicate the parameters.) There are two ways of specifying parameters -- first is to list them in the command line. For example try the following in the dos prompt.

EPGA.exe --help

It will just print a long help message. Then try

EPGA.exe  --maxGen=1000

It will run a GA like before, but will stop only after 1000 generations.

EPGA.exe  --maxGen=0 --steadyGen=20

will run the GA until 20 generations without any improvement.

So, you get the idea.

Now try this. First copy the file EPGA.exe.status to args.txt and edit the latter with notepad.

> copy EPGA.exe.status args.txt
> notepad args.txt

Notice that this file has all the arguments that can be given at the command line. # in a line means the rest that follows is a comment. Note that almost all the argments are commented. Now make sure only the following items are uncommented.

--vecSize=3  
--maxGen=0                             
--steadyGen=20

Now, run the program with the following command.

EPGA.exe @args.txt

Notice that this is equivalent to running

EPGA.exe --vecSize=3  --maxGen=0  --steadyGen=20

Within Visual Studio

To make things a bit easier for us, lets do the following. Move the file args.txt to the data folder.

> move args.txt ..\..\data\.

Then in your project in visual C++, add the file data.txt to resource files tab, in solutions explorer. (This step is optional)

Finally, add the following

@..\..\data\args.txt

to the Command argments Configuration properties->Debugging.

Now within visual C++ itself, you can just modify the file args.txt to suit your needs, save it and re-run our program.

Writing our own cost function

Now let's turn into our original problem. We need to minimize the diameter of seven pipes while maintaining reasonable (>10m) pressure at all supply nodes. Lets forget the pressure part for a moment and concentrate on minimizing the diameter. (The answer here is obvious, if pressure is no concern, then the 'best' diameter is zero!! -- but let's live with this silly notion for the moment.)

Do the following changes:

  • First we change the args.txt file to have
--vecSize=7 # we have seven pipes, each diameter can be represented by a single real value. 
--initBounds=7[0,500]             # -B : Bounds for variables -- pipe diameter within 0-500mm
--objectBounds=7[0,500]             # -B : Bounds for variables -- pipe diameter within 0-500mm
  • Change the cost function real_value.h to the following:
#include <vector>
#include <iostream>
using namespace std;
double real_value(const std::vector<double>& _ind)
{
  //GA returns diameter as ind_
  double length=1000;
  double factor=1.; //some factor so that cost=length=diameter*factor (lets keep things simple!)
  double dia,cost = 0;
  for (unsigned i = 0; i < _ind.size(); i++){
      cost+=_ind[i]*length*factor;
  }
  return cost/10000;
}

If everything is all right, you will have some large initial cost, and a very small final cost.


Now that we have customized the GA to represent our silly optimization problem, it is but a small step to do the real job!

In comes EPANet 2

With the provided EPANET toolkit (in epanet_tools folder) there is a help file: TOOLKIT.HLP. This is going to be our standard reference to various calls to epanet program via toolkit.

Let's do most of the changes in the real_value.h file and try to keep changes in RealEA.cpp to a minimum.

We will focus on several toolkit functions:

ENOpen and ENClose

Declaration
int ENopen( char* f1, char* f2, char* f3)
Description
Opens the Toolkit to analyze a particular distribution system.
Declaration
int Enclose(void)
Description
Closes down the Toolkit system (including all files being processed).

ENSolveH

Declaration
int ENsolveH( void )
Description
Runs a complete hydraulic simulation with results for all time periods written to the binary Hydraulics file.

ENGetNodeValue

Declaration
int  ENgetnodevalue( int index, int paramcode, float* value )
Description
Retrieves the value of a specific link parameter.

ENSetLinkValue

Declaration
int  ENsetlinkvalue( int index, int paramcode, float value )
Description
Sets the value of a parameter for a specific link.

Call EPANet 2

Do the following changes in RealEA.cpp.

  try
  {
  // first initialize the Epanet
  epanet_init(); // <-- new addition A function call to initialize epanet. we have to write this function. 
 
  eoParser parser(argc, argv);  // for user-parameter reading
...
  // close Epanet
  epanet_close(); // <-- new addition A function call to close epanet. we have to write this function. 
 
  }
  catch(exception& e)

Now let's do the major modifications in real_value.h

As the first stage:

#include <vector>
#include <iostream>
#include "epanet2.h"
using namespace std;
double dia_cost_factor=1.; //some factor so that cost=length=diameter*factor (lets keep things simple!)
 
/** A function that computes the cost. This is what the GA use to evaluate its populations */
double real_value(const std::vector<double>& _ind)
{
  //GA returns diameter as ind_
  double length=1000; /* All pipe lengths are equal */
 
  double dia,cost = 0;
  for (unsigned i = 0; i < _ind.size(); i++){
      cost+=_ind[i]*length*dia_cost_factor;
  }
  return cost/10000;
}
 
/* We open the epanet system with the necessary input file. 
A bit of hard coding here. But, lets live with that for the moment. */
void epanet_init(){
	int ret;
	char file[500]="../../data/network.inp";
	char rept[500]="../../data/network.rep";
 
	ret=ENopen(file,rept,"");
	cout << "At opening Epanet retured : "<<ret<<'\n';
 
}
/* Close the epanet system */
void epanet_close(){
	int ret;
    ret=ENclose();
	cout << "At closing Epanet retured : "<<ret<<'\n';
 
}


To run the above you will have to

  1. Add ..\..\epanet_tools to additional include directories.
  2. Add epanet2vc.lib to additional dependencies.
  3. Add ..\..\epanet_tools to additional library directories (At this stage the application should compile, but will give a runtime error.)
  4. Add PATH=%PATH%;..\..\epanet_tools to debugging environment. (Project properties->Debugging->Environment)


Run the application at this stage to make sure that the two epanet calls return zero (error free call signal).

Then add a function pressure_cost to real_value.h to compute the 'cost' of pressure deficiency. (Something like the one below)

/* Returns the pressure cost (penalty for pressure violations at demand nodes) based on epanet runs.
Prerequisites: The epanet system should be initialized before calling this function for the first time. */
double pressure_cost(vector<double> _ind){
	int ret;
	double cost;
	for(unsigned int i=0;i<npipes;i++){
		int index=-1;
		ret=ENgetlinkindex(pipes[i],&index);
		//cout << "At opening Epanet retured : "<<ret<<'\n';
		ret=ENsetlinkvalue(index,EN_DIAMETER,_ind[i]);
		//cout << "At opening Epanet retured : "<<ret<<'\n';
	}
	//now run the simulation
		ret=ENsolveH();
		//cout << "At solve Epanet retured : "<<ret<<'\n';
		cost=0;
    //read the pressure values
	for(unsigned int i=0;i<nnodes;i++){
		int index=-1;
		ret=ENgetnodeindex(nodes[i],&index);
		float value;
		//cout << "At ENgetnodeindex Epanet retured : "<<ret<<'\n';
		ret=ENgetnodevalue(index,EN_PRESSURE,&value);
		//cout << "At ENgetnodevalue Epanet retured : "<<ret<<'\n';
		if(value<10){
			cost+=pressue_cost_factor*(10-value); // if p<10m, set a proportional penalty. 
		}
	}
 
	//cout << "At ENcloseH Epanet retured : "<<ret<<'\n';
	return cost;
 
 
}

The value of variable pressure_cost_factor should be carefully considered (against that of dia_cost_factor).

Finally modify real_value function so that it will call the above pressure_cost function and add the cost to the total cost.

At this stage you have a complete living-breathing program that join the power to evolving objects with Epanet.

A touch of sophistication -- let's get rid of hard coding

This section is here mostly for the sake of completion. Ignore this section if you don't have time or inclination.

We can change the behavior of the GA without recompiling the code, thanks to the sophistication of the design of EO library. However, we have given up some of this flexibility in the way we have designed our cost function. We have hard coded a number of items:

  1. Name of the network file.
  2. Number of pipes in the network.
  3. Number of nodes.
  4. IDs of pipes and nodes.

It is possible to make our program quite flexible in these aspects also. But it needs a bit of work. Let's see how it can be done. The first stage is to change the real_value.h so that instead of hard coded values, it can take values stored in variables. Then in the main function (RealEA.cpp) add the code necessary to read these from a text file supplied by user.

Lets define the text file format as follows:

<network file name>
<file name for the report to write into>
<no of pipes>
<PIPE_ID1>
...
<no of nodes>
<NODE_ID1>
...

That means something like the file below

..\..\data\network.inp
..\..\data\network.rpt
7
P1
P2
P3
P4
P5
P6
P7
5
J1
J2
J3
J4
J5

Then the modified program is as follows:

real_value.h
#include <vector>
#include <iostream>
#include "epanet2.h"
#include <fstream>
using namespace std;
#define MAX_PATH_LEN 500
#define MAX_LABEL_LEN 25
double pressure_cost(vector<double> _ind);
int npipes=7;
 
int nnodes=5;
 
char file[MAX_PATH_LEN];
char rept[MAX_PATH_LEN];
vector<string> nodes; // notice, now we use vectors instead of traditional arrays. 
vector<string> pipes;
 
  double dia_cost_factor=1.; //some factor so that cost=length=diameter*factor (lets keep things simple!)
  double pressue_cost_factor=1000000; //multiplier to 'map' pressue defficiency to cost. 
                                      // cost=(pressuredefficiency)*pmult
 
 
  /** read the text file specified by filename argument and obtain epanet related parameters */
  void parse_epanet_para(char* filename){
	  cout << "I read epanet related data from "<<filename<<"\n"; // inform the user
	  //open the file
	  ifstream myfile (filename);
	   if(!myfile.is_open()){ // this is important. 
		   cout << "I can not open the file:"<<filename <<" I quit!!\n";
		   exit(1);
	   }
	   myfile >> file; //read the name of the file
	   myfile >> rept; //read the name of the (new) report file
	   myfile >> npipes; //number of pipes
	   for(int i=0;i<npipes;i++){ // read those pipe ids
		   char tmp[MAX_LABEL_LEN];
		   myfile >>  tmp;
		   pipes.push_back(tmp);
	   }
		myfile >> nnodes; //number of junctions
	   for(int i=0;i<nnodes;i++){//those ids
		   char tmp[MAX_LABEL_LEN];
		   myfile >>  tmp;
		   nodes.push_back(tmp);
	   }
  }
 
double real_value(const std::vector<double>& _ind)
{
  // check for sanity 
	if(_ind.size()!=npipes){
		//raise hell
		cout << "Bloody murder!\n";
		cout << "Number of pipes and chromosome size mismatch!\n";
		exit(5);
	}
  //GA returns diameter as ind_
  double length=1000;
 
  double dia,cost = 0;
 
  cost=pressure_cost(_ind);
  for (unsigned i = 0; i < _ind.size(); i++){
      cost+=_ind[i]*length*dia_cost_factor;
  }
  return cost/10000;
}
 
double pressure_cost(vector<double> _ind){
	int ret;
	double cost;
	for(unsigned int i=0;i<npipes;i++){
		int index=-1;
		char tmp[MAX_LABEL_LEN]; // this gimmick here is to convet a c++ string to a c style char*
		strcpy(tmp,pipes[i].c_str()); // because epanet is writtin in old c, which does not accept strings.
		ret=ENgetlinkindex(tmp,&index);
		//cout << "At opening Epanet retured : "<<ret<<'\n';
		ret=ENsetlinkvalue(index,EN_DIAMETER,_ind[i]);
		//cout << "At opening Epanet retured : "<<ret<<'\n';
	}
	//now run the simulation
		ret=ENsolveH();
		//cout << "At solve Epanet retured : "<<ret<<'\n';
		cost=0;
    //read the pressure values
	for(unsigned int i=0;i<nnodes;i++){
		int index=-1;
		char tmp[MAX_LABEL_LEN]; // convert c++ string to c style char* 
		strcpy(tmp,nodes[i].c_str());
		ret=ENgetnodeindex(tmp,&index);
		float value;
		//cout << "At ENgetnodeindex Epanet retured : "<<ret<<'\n';
		ret=ENgetnodevalue(index,EN_PRESSURE,&value);
		//cout << "At ENgetnodevalue Epanet retured : "<<ret<<'\n';
		if(value<10){
			cost+=pressue_cost_factor*(10-value);
		}
	}
 
	//cout << "At ENcloseH Epanet retured : "<<ret<<'\n';
	return cost;
 
 
}
 
void epanet_init(){
	int ret;
 
 
	ret=ENopen(file,rept,"");
	cout << "At opening Epanet retured : "<<ret<<'\n';
 
}
 
void epanet_close(){
	int ret;
    ret=ENclose();
	cout << "At closing Epanet retured : "<<ret<<'\n';
 
}
RealEA.cpp
#define _CRT_SECURE_NO_DEPRECATE
//above is to get rid of deprecation warnings of Microsoft compiler. Needed because we use strcpy() function. 
#include <iostream>
#include <es/make_real.h>
#include "real_value.h"
#include <apply.h>
 
using namespace std;
typedef eoReal<eoMinimizingFitness> EOT;
void print_values(eoPop<EOT> pop);
int main_function(int argc, char* argv[]);
 
/** Notice that we have moved everything that was previously in main() to 
main_function. 
Now before GA related stuff is handled (by main_function), 
We process the command argument list. Unlike the previous case, now the first argument, i.e. 
the filename of the EPAnet related parameters, is mandatory. 
Then we copy the rest of the arguments in argv to a new array argv_ and pass it to main_function. 
From the GA viewpoint, nothing has changed. It receives a argument array. If there are no arguments in it, GA will 
run with default parameters. Otherwise it will parse the argument array. 
The first command line argument is separately passed parse_epanet_para function.
*/
int main(int argc,char *argv[]){
       /* argv[0] is always the name of the program. So, to run properly the program should have 
       length of argv (i.e. argc) >=2 
       If this is not the case, provide some help. */
	if(argc<2){// no arguments provided at the command line
		cout << "Usage: argv[0] <epanet_related_datafile> <EO related arguments ...>\n";
		cout << "Format of epanet_related_datafile as follows.\n";
		cout << "<network file name>\n";
		cout << "<file name for the report to write into>\n";
		cout << "<no of pipes>\n";
		cout << "<PIPE_ID1>\n";
		cout << "...\n";
		cout << "<no of nodes>\n";
		cout << "<NODE_ID1>\n";
		cout << "...\n";
		exit(1);
	}
	char* filename=argv[1]; // seperately copy argv[1] (first argument) to variable filename
	char* argv_[MAX_PATH_LEN]; 
	argv_[0]=argv[0];       // argv[0] is the calling program name, copy this as is. 
	for(int i=1;i<argc-1;i++){ // then copy the rest (argv[2], argv[3], ...) of arguments to new array
		cerr << argv[i+1];
		argv_[i]=argv[i+1];
	}
	argc--; // argc should be one less than before
	//now parse the parameter file stright away! 
	parse_epanet_para(filename);
	return main_function(argc,argv_); // now call main_function with new argc, argv_ pair. 
}
int main_function(int argc, char* argv[])
{
 
  try
  {
  // first initialize the Epanet
  epanet_init();
 
  eoParser parser(argc, argv);  // for user-parameter reading
  eoState state;   
  eoEvalFuncPtr<EOT, double, const std::vector<double>&> 
               mainEval( real_value );
  eoEvalFuncCounter<EOT> eval(mainEval);
  eoRealInitBounded<EOT>& init = make_genotype(parser, state, EOT());
  // Build the variation operator (any seq/prop construct)
  eoGenOp<EOT>& op = make_op(parser, state, init);
  // initialize the population - and evaluate
  // yes, this is representation indepedent once you have an eoInit
  eoPop<EOT>& pop   = make_pop(parser, state, init);
  // stopping criteria
  eoContinue<EOT> & term = make_continue(parser, state, eval);
  // output
  eoCheckPoint<EOT> & checkpoint = make_checkpoint(parser, state, eval, term);
  // algorithm (need the operator!)
  eoAlgo<EOT>& ea = make_algo_scalar(parser, state, eval, checkpoint, op);
  // to be called AFTER all parameters have been read!!!
  make_help(parser);
 
  // evaluate intial population AFTER help and status in case it takes time
  apply<EOT>(eval, pop);
  // print it out
  cout << "Initial Population\n";
  pop.sortedPrintOn(cout);
  cout << endl;
 
  cin.get();
  run_ea(ea, pop); // run the ea
 
  cout << "Final Population\n";
  pop.sortedPrintOn(cout);
  cout << endl;
 
  // close Epanet
  epanet_close();
 
  }
  catch(exception& e)
  {
    cout << e.what() << endl;
  }
	return 1;
}
Personal tools