ENGR 102 Engineering Lab I - ComputationWeek 05: Creating and Testing Larger Programs

Problem Solving

Writing larger programs1 involves similar skills to those for 1 These notes are based closely on aPowerPoint presentation prepared byDr. John Keyser for the Pilot Courseversion of ENGR 102.

solving any large problem. In fact, you cannot write a programto solve a complex engineering problem until you have derived adetailed solution strategy, complete with all of the steps to find asolution to the problem.2 Problem solving is a skill that requires 2 The subfield of computer science

dealing with the process of constructinglarge pieces of software is calledsoftware engineering.

You can view one such large projectto simulate oil spills on the Na-tional Oceanic and AtmosphericAdministration (NOAA) web servergnome.orr.noaa.gov. This model isbuilt using Python. Javascript gathersthe input data from the web interfaceand starts the program, but all of thesimulation work is done in Python.

practice, and often writing computer programs in engineering willseem like the equivalent of solving a brain teaser puzzle. As wethink about the process we use to solve complex problems, patternsemerge, and we can define various best practices.

Many problems in engineering are numerical in nature and relateto something we are designing, whether a physical object or a pro-cess. There are many approaches to problem solving, but each of thefollowing steps are often helpful:

• Clearly define the problem. As students, this is often providedto you by your instructors. As engineers, you often define theproblem through conversations with your clients. In either case,until you can state the problem in your own words, you probably donot fully grasp the problem you are to solve.

• Draw a picture. Sketch the key elements of the problem, includenumbers where appropriate, and write equations that may defineelements of the sketch.

• Outline a solution strategy. Write down the key elements of the so-lution strategy. Include in your list: required input data, equationsto solve, sequential steps to the solution, repeated or generalizedtasks.

• Solve for some cases by hand. You can test your solution strategyand gain insight on how to program the solution by solving forone or more cases of the problem by hand.

• Test the solution. Think of ways to check whether your handcalculations are correct. Also, as you start to create your computerprogram, use your hand calculations to test your program (or to

gnome.orr.noaa.gov

2 engr 102-213

test any software package you are using, but that is written bysomeone else).

• Use and improve the solution. Once you have a working programto solve a problem, exercise that program to solve similar prob-lems and for multiple test cases, trying to find errors or problemswith the code and seeking to improve and generalize it.

We will demonstrate these steps to problem solving in the lectureand the labs this week, solving engineering problems with growingcomplexity. In these lecture notes, we will also show how to applythese steps to program development and explain a few programmingbest practices.

Example Problem

In the lecture today, we will write a program to do a common taskin municipal government and surveying. Whenever you apply for apermit to do something regulated by a local, state, or federal govern-mental agency, you must clearly state where that activity will takeplace. As an example, assume that we would like to drill a drinkingwater well near Wixon Valley, Texas. In this part of Texas, the landsurvey is organized by Blocks. Figure 1 shows the blocks near WixonValley, with the location of our well of interest W marked in orange.We can immediately see by looking at the map that this dot is withinBlock 16 (outlined by the polygon ABCD).

State Plane Coordinates Zone TX C-4203 (Dimensions in m)

3,127,482.653 N1,083,666.037 E

3,129,730.776 N1,081,094.743 E

3,133,639.561 N1,084,602.605 E

3,131,347.27 N1,087,156.270 E

3,130,187.096 N1,083,606.857 E

A

B

C

D

W

P

Q

Figure 1: Map of Wixon Valley, Texas,showing survey Block 16 (polygonABCD) and one well (orange dot atW) inside the survey block. Q is duenorth of W, and P is the point that is aminimum distance from W to the lineBC.

Spatial coordinates on the globe are usually measured in degrees,minutes, and seconds, and these mark out regions on the surface ofan oblate spheroid. Locally, we can define a plane in (x, y) Cartesian

engr 102 engineering lab i - computation 3

space that is tangent to the globe. Surveyors have a standard for this,and in the United States, we often use the State Plane CoordinateSystem. The map in Figure 1 is from the Texas General Land Office(TGLO).3 The TGLO map reports location in latitude and longitude. 3 Obtained by navigating the interactive

map at http://gisweb.glo.texas.gov/glomapjs/index.html

These points were converted to State Plane Coordinates4 and then

4 Using the coordinate converter athttps://www.ngs.noaa.gov/NCAT/

reported in the figure in units of meters.To fill out the well permit for one well, it is probably easiest to

plot that well location by hand on a map (as is shown in Figure 1). Ifmany wells must be permitted, it may be faster and more reliable towrite a computer program.5 5 When I was an engineering intern

at Wright Water Engineers, Inc. inDenver, Colorado, I was asked to findthe section numbers (equivalent toblock numbers, but used in other partsof the U.S., including parts of Texas)for 500 wells a client needed to drill. Iwas given the State Plane Coordinatesof each well; after tediously plottingabout 10 of them by hand, I decidedit would be faster to write a computerprogram. I coded the locations of thesection lines and then was able toget the section numbers for all 500wells in less than a second. It tookme about 12 hours to write and testmy computer program—a few hoursmore than it would have taken me todo everything by hand. But, once mycompany validated and approved myprogram, they immediately acceptedanother job to write the permits for 750additional wells—which took a veryshort time to categorize into sections.

In this lecture, we would like to develop a program that takes theState Plane Coordinate (northing and easting in m) of a well andoutputs whether or not that well is in Block 16. We would also liketo determine which boundary is closest to the well and what theminimum distance is from the well to that boundary.6 If we had a

6 Do you understand the problem? Canyou state it in your own words.

similar program code defining all the surrounding survey Blocks,then we could quickly determine the Block for each well coordinatewe were given.7

7 Before reading on, take a few minutesto think about how your eye and brainknew the well marked by the orangedot was inside Block 16. How couldyou tell a computer to make the sameassessment?

Program Design

There are two main approaches you can take to write a large pro-gram, and we will define these approaches by an analogy to architec-ture using pyramids and arches.

In a pyramid, you place stones stably at the bottom. Once thestones are firmly in place underneath, you can place more stoneson top of them. At any time during construction, you have a stablestructure that supports itself. You can also test the lower levels beforeadding upper levels.

By constrast, in an arch, you place stones on an underlying sup-porting structure. The support structure must be constructed beforeany of the arch can be built. Until you place the last stone in place,you do not have a stable structure. You cannot really test the arch orremove its support structure until all pieces are in place.

While both types of construction yield beautiful architecturalresults, we prefer to build computer codes like pyramids. Start withsmall sections of code. Test these sections and ensure that they bothoperate and give the expected results before adding additional code.In this approach, you should always have a working computer code,and you are much more likely to find errors or weaknesses in yoursolution early before more of the code it built. Also, if you test eachsmall addition to the code, you should always have a solution thataccurately reflects your chosen solution strategy.

Solution Design for Well Categorizing Example

Let us now turn our attention to our example problem of classifyinga well as inside or outside of survey Block 16 in Wixon Valley, Texas.

http://gisweb.glo.texas.gov/glomapjs/index.htmlhttp://gisweb.glo.texas.gov/glomapjs/index.htmlhttps://www.ngs.noaa.gov/NCAT/

4 engr 102-213

We should follow the problem solving steps outlined in the firstsection above, and as we develop our program solution, we shouldidentify pieces of the problem we can code separately/sequentially inthe pyramid-approach to program development.

In the example statement above, we have already clearly definedthe problem and drawn a picture. Now, we can turn our attention toa solution strategy. There may be many ways to do this, and someof these ways may involve clever mathematics. The approach wewill take here will be to use if-block statements to “fence in thewell” with equations describing each side of the polygon ABCD. Thisapproach is based on what our eyes do to classify the well. For me,I notice that the well is south of the lines BC and CD and north ofthe lines AB and AD.8 Hence, the solution strategy will be to write 8 Likewise, you may have classified the

location in terms of being east of linesAB and BC and west of a lines CD andAD. Do you think we need to makeboth the north-south and the east-westchecks in our code? Why or why not?

down equations for each line and then test whether the well is on theside of the line that is classified as inside Block 16.9

9 Notice that for the well to be insidethe polygon, it must be on the correctside of all of the lines defining thepolygon. Hence, we will use a kind ofand-based logical structure in our code.

If we used the arch-style of programming, we would start bywriting the complete set of if-statements necessary to categorize thewell with respect to all of the lines. If the code got the answer wrong,we would have to check many different if-statements and equationsto figure out which one is wrong.

Instead, using the pyramid approach to programming design,we should start by creating an equation for one line segment, forinstance line BC. Once we code this line, we should test one or twopoints along the line to verify the equation for the line is codedcorrectly. After these tests pass, we can add the if-statement thatchecks whether or not the well is on the correct side of this line to beclassified as potentially inside the polygon, i.e., whether the well issouth of that line.

Now that we have a general approach to the solution, we can writedown our solution strategy with more details and more of the stepsthat will be required in our computer program:

• Collect inputs for the coordinates of the line BC and the coor-dinates of the well. We will let easting be along the x-axis andnorthing be along the y-axis. We will name our variables with theletter name of the point and a subscript for the x- and y-directions,e.g., for point B, the x-coordinate will be B_x.

• Create an equation for the line BC. A general equation for this lineis:

y =Cy − ByCx − Bx

(x − Bx) + By (1)

• Compute the value of y on the line BC that has the same value of xas the x-coordinate of the well. That is, find the y-value of point Qin Figure 1 using Equation (1).

• Decide if the well is south of the line BC by comparing Qy to Wy. Ifno, call this False since this condition must be true for the well tobe inside of Block 16. Note that this is not the only condition that

engr 102 engineering lab i - computation 5

must be true, but it is one of them, and it is the condition we aretesting with our first small block of code.

Writing Tests for Your Code

The process of designing and writing tests for a computer code isso important that there are whole Python packages dedicated tosupporting their implementation in program design.10 These are 10 See for example, the unittest module

of Python.sometimes called unit tests because they test a single element of theprogram. For our purposes, we will simply call them tests, and wewill design tests to check the accuracy of our computed solutions andthe ability of our program to handle many possibilities.

An example for checking the accuracy of our computed solutionwould be to code the programming piece outlined above (i.e., lineBC and whether or not the well is to the south of it). Once this smallblock is done, run the code and print the value of Qy and whetherthe result is True or False. For the well shown in Figure 1, the correctanswer should be True.11 11 Can you think of any other quantities

you could check to determine whetheror not your solution strategy andcomputer program is correct?

When we create test cases, we often try to think of all the thingsthat might happen when we run our code and then make sure thatall of these cases are handled properly by our programs. We call testcases that fall somewhat outside the norm edge cases.12 Some of the 12 This term comes from an analogy to

a chess board. Any cell in the middleof the board surrounded by eight othercells is a normal case. The edge caseswould be cells on the sides, surroundedby five neighbors, and cells in thecorners, surrounded by three neighbors.

test and edge cases in this example might include:

• Wells that fall directly on any boundary

• Wells that fall exactly on the intersection of any two boundaries

• Wells that are east or west of Block 16

• Wells that are north or south of Block 16

As we define the unit tests for our well program, it would be a goodidea to have at least one sample for each of these cases.

Commenting Code and Using Whitespace

As we have already seen in the lab assignments in past weeks, weshould use comments throughout our programs to explain what thecode is doing. Comments are just statements in our programs thatare ignored by the compiler or interpreter. In Python, we precedecomments by #. Comments can be on a line by themselves, as in

# This is a stand-alone comment

or they may come after an executable command on the same line asthat command, as in

velocity = 12.45 # velocity of car in m/s

We use comments in programs to

• Help others to read our code

6 engr 102-213

• Help us to read and remember our code sometime in the future

• Organize elements of a larger project into manageable sections andto document what each section is doing.

• Include references to external sources of information (e.g., a book,journal articles, reference manuals, websites, etc.)

• Describe the purpose of a line or section of code

• Define the purpose of a particular variable

• Clarify a computation that is not immediately obvious

In general, all comments are good, but you should be careful notto overuse them. For instance, you to not need to comment what isobvious in the code itself as in the poor example:

# Add 1 to x

x = x+1

When we are dealing with a larger programming project, we canuse comments to layout the structure of our program which we thenfill in with executable lines of code. Continuing with our example,we may write:

# Pre-processor ----------------------------------------------------------

# Enter the location of the well of interest

# Enter the locations of the points B and C defining a boundary of

# Block 16. Coordinates are in m; x is in the easting direction and y is

# in the northing direction.

# Processor --------------------------------------------------------------

# Initialize a variable that stores whether the well is inside Block 16

# (True) or not (False)

# Compare well position to line BC

# --------------------------------

# Compute the equation of line BC.

# Get y-coordinate of well projected onto line BC.

# Check if well is on the side of this line that is inside the polygon;

# locations to the north of line BC are outside the polygon.

# Post-processor (unit tests) --------------------------------------------

# Print the y-value of point Q and the value of our variable storing the

# True/False value of the well status.

engr 102 engineering lab i - computation 7

Notice that we have inserted a blank line between each comment andwe have used a line of dashes to indicate a significant heading forthe block of code that does the calculations related to line BC. Evenafter we fill in the missing executable code, we will keep these lineseparations to help indicate that one task is complete and a new taskis beginning. Hence, we should use both comments and white spaceto make our programs more readable and understandable.

Building Your Computer Program

Now, we should take these concepts and apply them in creating thecomputer code to solve our problem. The code block to solve our firststep might be:

# Pre-processor ----------------------------------------------------------

# Enter the location of the well of interest

well_x = 1083606.857 # easting coordinate in m

well_y = 3130187.096 # northing coordinate in m

# Enter the locations of the points B and C defining a boundary of

# Block 16. Coordinates are in m; x is in the easting direction and y is

# in the northing direction.

B_x = 1081094.743

B_y = 3129730.776

C_x = 1084602.605

C_y = 3133639.561

# Processor --------------------------------------------------------------

# Initialize a variable that stores whether the well is inside Block 16

# (True) or not (False)

in_block16 = True

# Compare well position to line BC

# --------------------------------

# Compute the equation of line BC.

m = (C_y - B_y) / (C_x - B_x)

# Get y-coordinate of well projected onto line BC.

well_BC = m * (well_x - B_x) + B_y

# Check if well is on the side of this line that is inside the polygon;

# locations to the north are outside the polygon.

if well_y > well_BC:

in_block16 = False

# Post-processor (unit tests) --------------------------------------------

8 engr 102-213

print(’The location of point Q is ’ + well_BC)

print(’The well is currently classified as inside the polygon: ’ +

in_block16)

Notice in the post processor that once we added these print state-ments, we deleted the comment about them since these print state-ment are self-explanatory.

Best Practices in Writing Computer Programs

We will close this set of lecture notes by reviewing a list of things wehave learned so far that all add up to good programming practice. Bemindful of each of these things as you develop your programs thisweek. These are:13 13 This list is adapted from a list by

Larry Nyhoff and Sanford Leestma,originally published in Fortran 77 forEngineers and Scientists, 2nd edition,Macmillian Publishing Company: NewYork, 1988.

• Programs cannot be considered correct until they have been vali-dated using test data.

• Programs should be readable and understandable. Use meaning-ful variable names that suggest what each variable represents.Assign constants to variables defined near the top of your codesrather than hard-wiring values in the equations throughout yourprogram.

• Use comments to describe the purpose of a program, the meaningof variables, and the purpose of key program segments.

• Label or document all output produced by a program.

• Programs should be efficient. Do not compute the same valuetwice—instead define a variable and make the computation once.Avoid copying computer code (but, we need to learn iterationbefore we can fully implement this...so for now, when you copycomputer code, change as little as possible in each pasted codeblock and make each block look and act nearly identical to itsother copies.)

• Programs should be general and flexible.

• Use parenthesis to override the normal order of operations and tomake the intent of calculations or boolean operations more clear.

• Implicitly define your data types when you create variables whenthis is possible. For instance, if a variable will be used as a realnumber, create it as a real number, either by including a decimal orby using the float() function.

• Include a comment block at the top of your programs that statesthe program name, a brief description of what the program does,the name of the program author, and a date.

engr 102 engineering lab i - computation 9

• Break up long expressions into simpler subexpressions whenpossible.

• Use white space and comments to delineate separate sections of alarger program organization.

Problem SolvingExample ProblemProgram DesignSolution Design for Well Categorizing ExampleWriting Tests for Your CodeCommenting Code and Using WhitespaceBuilding Your Computer ProgramBest Practices in Writing Computer Programs