Lab46 Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<WRAP centeralign round box>
<WRAP><color red><fs 200%>Corning Community College</fs></color></WRAP>
<WRAP><fs 150%>CSCS1320 C/C++ Programming</fs></WRAP>
</WRAP>

======Project: ALGORITHMS - PRIME NUMBER CALCULATION (pnc0)======

=====Errata=====
With any increasingly complex piece of code or environment, we must find effective means of organizing various processes or communications. This "Errata" section and related updates are one such instance of that; intended as a means of disseminating information on changes to the project, you can be informed what modifications have taken place, along with any unique actions you need to take to compensate.

Any typos, bugs, or other updates/changes to the project will be documented here.

====Revision List====

  * revision #: <description> (DATESTRING)

Some changes may involve updates being made available to the project, in which case you'll be prompted with such notification and can run the available updating commands to synchronize your copy of the project with the changes.

=====Objective=====
To apply your skills in the implementation of prime number calculating algorithms.

=====Background=====
In mathematics, a **prime** number is a value that is only evenly divisible by 1 and itself; it has just that one pair of factors, no others. Numbers that have divisibility/factors are classified as **composite** numbers.

The number **6** is a **composite** number, as in addition to 1 and 6, it also has the factors of 2 and 3.

The number **17**, however, is a **prime** number, as no numbers other than 1 and 17 can be evenly divided into it.

=====Calculating the primality of a number=====
As of yet, there is no quick and direct way of determining the primality of a given number. Instead, we must perform a series of tests to determine if it fails primality (typically by proving it is composite).

This process incurs a considerable amount of processing overhead on the task, so much so that increasingly large values take ever-expanding amounts of time. Often, approaches to prime number calculation involve various algorithms, which offer various benefits (less time) and drawback (more complex code).

Your task for this project is to implement a prime number program using the straightforward, unoptimized brute-force algorithm, which determines the primality of a number in a "trial by division" approach.

=====Main algorithm: brute force (primereg)=====
The brute force approach is the simplest to implement (although at some cost). 

As we will be looking to do some time/performance analysis and comparisons, it is often good to have a baseline. This program will be it.

To perform the process of computing the primality of a number, we simply attempt to evenly divide all the values between 2 and one less than the number in question. If any one of them divides evenly, the number is **NOT** prime, but instead composite.

Checking the **remainder** of a division indicates whether or not a division was clean (having 0 remainder indicates such a state).

For example, the number 11:

<code>
11 % 2 = 1 (2 is not a factor of 11)
11 % 3 = 2 (3 is not a factor of 11)
11 % 4 = 3 (4 is not a factor of 11)
11 % 5 = 1 (5 is not a factor of 11)
11 % 6 = 5 (6 is not a factor of 11)
11 % 7 = 4 (7 is not a factor of 11)
11 % 8 = 3 (8 is not a factor of 11)
11 % 9 = 2 (9 is not a factor of 11)
11 % 10 = 1 (10 is not a factor of 11)
</code>

Because none of the values 2-10 evenly divided into 11, we can say it passed the test: **11 is a prime number**

On the other hand, take 119:

<code>
119 % 2 = 1 (2 is not a factor of 119)
119 % 3 = 2 (3 is not a factor of 119)
119 % 4 = 3 (4 is not a factor of 119)
119 % 5 = 4 (5 is not a factor of 119)
119 % 6 = 5 (6 is not a factor of 119)
119 % 7 = 0 (7 is a factor of 119)
119 % 8 = 7
119 % 9 = 2
119 % 10 = 9
119 % 11 = 9
119 % 12 = 11
119 % 13 = 2
...
</code>

Because, during our range of testing every value from 2-118, we find that 7 evenly divides into 119, it failed the test: 119 is **not** prime, but is instead a composite number.

Please NOTE: Even once a number is identified as composite, your **primereg** MUST **CONTINUE** evaluating the remainder of the values (up to 119-1, or 118). It might seem pointless (and it is for a production program), but I want you to see the performance implications this creates.

====algorithm====
Some things to keep in mind on your implementation:

  * you will want to use loops (no less than 2, no more than 2) for this program.
    * a nested loop makes the most sense:
      * an outer loop that drives the progression of each sequential number to be tested
      * an inner loop that tests that current number to see if it has any factors
  * you know the starting value and the terminating condition, so you have a clear starting and ending point to work with.
  * I do **NOT** want to see ambiguous, one-letter variables used in your implementation(s). Please use //meaningful// variable names.
    * Some good examples of variable names would be:
      * **number**: the number being tested
      * **factor**: the value being divided into number to test for primality
      * **step**: the rate by which some variable is changing
      * **qty**: the count of the current tally of primes
      * **max**: the maximum count we seek
      * **start**: a value we are starting at
      * **lower**: a lower bound
      * **upper**: an upper bound
      * see how much more readable and meaningful these are, especially as compared to **a**, **i**, **n**, **x**? You may even find it helps with debugging and understanding your code better.
  * let the loops drive the overall process. Identify prime/composite status separate from loop terminating conditions.
    * and remember, the baseline brute force algorithm (**primereg**) may well identify a value as composite, but won't terminate the loop.
  * your timing should start before the loop (just AFTER argument processing), and terminate immediately following the terminating output newline outside the loops.

=====prime algorithm implementation=====
For simplicity, I have encoded important implementation information into the file name (and therefore resulting executable/binary) that will correspond to the indicated algorithm plus any optimizations.

To break it down, all prime programs will be of the form:
  * primeALG[O...]
    * where each and every program starts with "prime"
    * is immediately followed by a 3-letter (lowercase) abbreviation of the algorithm to be implemented (**reg**, for instance)
    * and then is followed by 0 or more layered attributes describing the particular optimization that is applied (again, if any: **zero** or more).

Unless specified in the encoded name, your algorithm should only implement the algorithm and optimization(s) specified.

That is, if your program to implement is **primereg**, that means you are ONLY to implement the brute force algorithm, in all its unoptimized, inefficient glory. This is important for establishing separate data points for analytical comparison (with future projects).

=====Programs=====
It is your task to write the following prime number variants:

  - **primereg.c**: our baseline (does JUST the process, no optimizations)

====Program Specifications====
Your program should:
  * obtain 2-4 parameters from the command-line (see **command-line arguments** section below).
    * check to make sure the user indeed supplied enough parameters, and exit with an error message if not.
    * argv[1]: maximum quantity of primes to calculate (your program should run until it discovers **that** many primes).
      * this value should be an integer value, greater than or equal to 0.
        * if argv[1] is 0, disable the quantity check, and rely on provided lower and upper bounds (up to argv[4] would be required in this case).
    * argv[2]: reserved for future compatibility; for now, require and expect it to be **1**.
    * argv[3]: **conditionally optional** lower bound (starting value). Most of the time, this will probably be **2**, but should be a positive integer greater than or equal to 2. This defines where your program will start its prime quantity check from.
      * if omitted, assume a lower bound of **2**.
      * if you desired to specify an upper bound (argv[4]), you obviously MUST provide the lower bound argument under this scheme.
    * argv[4]: **conditionally optional** upper bound (ending value). If provided, this is the ending value you'd like to check to.
      * If doing a quantity run (argv[1] is NOT 0), this value isn't necessary.
      * If doing a quantity run AND you specify an upper bound, whichever condition is achieved first dictates program termination. That is, upper bound could override quantity (if it is achieved before quantity), and quantity can override the upper bound (if it is achieved before reaching the specified upper bound).
    * for each argument: you should do a basic check to ensure the user complied with this specification, and exit with a unique error message (displayed to STDERR) otherwise:
      * for insufficient quantity of arguments, display: **PROGRAM_NAME: insufficient number of arguments!**
      * for invalid argv[1], display: **PROGRAM_NAME: invalid quantity!**
      * for invalid argv[2], display: **PROGRAM_NAME: invalid value!**
      * for invalid argv[3], display: **PROGRAM_NAME: invalid lower bound!**
        * if argv[3] is not needed, ignore (no error displayed not forced exit, as it is acceptable defined behavior).
      * for invalid argv[4], display: **PROGRAM_NAME: invalid upper bound!**
        * if argv[4] is not needed, ignore (no error displayed nor forced exit, as it is acceptable defined behavior).
      * In these error messages, **PROGRAM_NAME** is the name of the program being run; this can be accessed as a string stored in **argv[0]**.
  * implement ONLY the algorithm and optimization(s) specified in the program name. We are producing multiple data points for a broader performance comparison.
  * please take note on differences in run-time, contemplating the impact the algorithm and optimization(s) have on performance (timing, specifically).
  * immediately after argument processing: start your stopwatch (see **timing** section below).
  * perform the correct algorithm and optimization(s) against the command-line input(s) given.
    * each program is to have no fewer and no more than 2 loops in this prime processing section.
  * display identified primes (space-separated) to **STDOUT**
  * stop your stopwatch immediately following your prime processing loops (and terminating newline display to **STDOUT**). Calculate the time that has transpired (ending time minus starting time).
  * output the processing run-time to **STDERR**
  * your output **MUST** conform to the example output in the **execution** section below. This is also a test to see how well you can implement to specifications. Basically:
    * as primes are being displayed, they are space-separated (first prime hugs the left margin), and when all said and done, a newline is issued (to **STDOUT**).
    * the timing information will be displayed in accordance to code I will provide below (see the **timing** section).

=====Grabit Integration=====
I have made some skeleton files and a custom **Makefile** available for this project. Since we've amassed considerable experience manually compiling our files, it is time to start experiencing some of the other development tools that can automate or facilitate various processes.

I have written a tool, known as **grabit**, which will let you obtain the files I have put together for this project. To "grab" it:

<cli>
lab46:~/src/cprog$ grabit cprog pnc0
make: Entering directory '/var/public/SEMESTER/cprog/pnc0'
Commencing copy process for SEMESTER cprog project pnc0:
 -> Creating project pnc0 directory tree           ... OK
 -> Copying pnc0 project files                     ... OK
 -> Synchronizing pnc0 project revision level      ... OK
 -> Establishing sane file permissions for pnc0    ... OK

*** Copy COMPLETE! You may now go to the '/home/USER/src/cprog/pnc0' directory ***

make: Leaving directory '/var/public/SEMESTER/cprog/pnc0'
lab46:~/src/cprog/$ 
lab46:~/src/cprog$ cd pnc0
lab46:~/src/cprog/pnc0$ ls
Makefile      primereg.c
lab46:~/src/cprog/pnc0$ 
</cli>

NOTE: You do NOT want to do this on a populated pnc0 project directory-- it will overwrite files.

And, of course, your basic compile and clean-up operations via the Makefile.

=====Makefile operations=====
Makefiles provide a build automation system for our programs, instructing the computer on how to compile files, so we don't have to constantly type compiler command-lines ourselves. I've also integration some other useful, value-added features that will help you with overall administration of the project.

Basic operation of the Makefile is invoked by running the command "**make**" by itself. The default action is to compile everything in the project directory.

Additional options are available, and they are provided as an argument to the make command. You can see the available options by running "**make help**":

<cli>
lab46:~/src/cprog/pnc0$ make help
*******************[ C/C++ Programming pnc0 Project ]*******************
** make                     - build everything                        **
** make showerrors          - display compiler warnings/errors        **
**                                                                    **
** make debug               - build everything with debug symbols     **
** make checkqty            - runtime evaluation for qty              **
** make checkrange          - runtime evaluation for range            **
**                                                                    **
** make verifyqty           - check implementation for qty validity   **
** make verifyrange         - check implementation for range validity **
** make verifyall           - verify project specifications           **
**                                                                    **
** make save                - create a backup archive                 **
** make submit              - submit assignment (based on dirname)    **
**                                                                    **
** make update              - check for and apply updates             **
** make reupdate            - re-apply last revision                  **
** make reupdate-all        - re-apply all revisions                  **
**                                                                    **
** make clean               - clean; remove all objects/compiled code **
** make help                - this information                        **
************************************************************************
lab46:~/src/cprog/pnc0$ 
</cli>

A description of some available commands include:

  * **make**: compile everything
    * any **warnings** or **errors** generated by the compiler will go into a file in the base directory of pnc0 in a file called **errors**; you can **cat** it to view the information.
  * **make debug**: compile everything with debug support
    * any **warnings** or **errors** generated by the compiler will be displayed to the screen as the programs compile.
  * **make clean**: remove all binaries
  * **make save**: make a backup of your current work
  * **make submit**: archive and submit your project

The various "check" options do a runtime performance grid, allowing you to compare timings between your implementations.

The various "verify" options do more aggressive checks, helping to ensure your project falls within stated project specifications.

Just another "nice thing" we deserve.
=====Command-Line Arguments=====
To automate our comparisons, we will be making use of command-line arguments in our programs.

====header files====
We don't need any extra header files to use command-line arguments, but we will need an additional header file to use the **atoi(3)** function, which we'll use to quickly turn the command-line parameter into an integer, and that header file is **stdlib.h**, so be sure to include it with the others:

<code c>
#include <stdio.h>
#include <stdlib.h>
</code>

====setting up main()====
To accept (or rather, to gain access) to arguments given to your program at runtime, we need to specify two parameters to the main() function. While the names don't matter, the types do.. I like the traditional **argc** and **argv** names, although it is also common to see them abbreviated as **ac** and **av**.

Please declare your main() function as follows:

<code c>
int main(int argc, char **argv)
</code>

There are two very important variables involved here (the types are actually what are important, the names given to the variables are actually quite, variable; you may see other references refer to them as things like "ac" and "av"):

  * int argc: the count (an integer) of tokens given on the command line (program name + arguments)
  * <nowiki>char **argv</nowiki>: an array of strings (technically an array of an array of char) that contains "strings" of the various tokens provided on the command-line.

The arguments are accessible via the argv array, in the order they were specified:

  * argv[0]: program invocation (path + program name)
  * argv[1]: our maximum / upper bound
  * argv[2]: reserved value, should still be provided and be a 1 for this project
  * argv[3]: conditionally optional; represents lower bound
  * argv[4]: conditionally optional; represents upper bound

Additionally, let's not forget the **argc** variable, an integer, which contains a count of arguments (argc == argument count). If we provided argv[0] through argv[4], argc would contain a 5.

===example===
For example, if we were to execute the **primereg** program:

<cli>
lab46:~/src/cprog/pnc0$ ./primereg 128 1 2 2048
</cli>

We'd have:

  * <nowiki>argv[0]</nowiki>: "./primereg" 
  * <nowiki>argv[1]</nowiki>: "128" (note, NOT the scalar integer 128, but a string) 
  * <nowiki>argv[2]</nowiki>: "1"
  * <nowiki>argv[3]</nowiki>: "2" 
  * <nowiki>argv[4]</nowiki>: "2048" 

and let's not forget:

  * argc: 5   (there are 5 things, argv indexes 0, 1, 2, 3, and 4)

With the conditionally optional arguments as part of the program spec, for a valid execution of the program, argc could be a value anywhere from 3 to 5.

====Simple argument checks====
While there are a number of checks we should perform, one of the first should be a check to see if the minimal number of arguments has been provided:

<code c>
    if (argc < 3)  // if less than 3 arguments (program_name + quantity + argv[2] == 3) have been provided
    {
        fprintf(stderr, "%s: insufficient number of arguments!\n", argv[0]);
        exit(1);
    }
</code>

Since argv[3] (lower bound) and argv[4] (upper bound) are conditionally optional, it wouldn't make sense to check for them in the overall count. But we can and do still want to stategically utilize **argc** to determine if an argv[3] or argv[4] is present.

====Grab and convert max====
Finally, we need to put the argument representing the maximum quantity into a variable.

I'd recommend declaring a variable of type **int**.

We will use the **atoi(3)** function to quickly convert the command-line arguments into **int** values:

<code c>
    max  = atoi (argv[1]);
</code>

And now we can proceed with the rest of our prime implementation.

=====Timing=====
Often times, when checking the efficiency of a solution, a good measurement (especially for comparison), is to time how long the processing takes.

In order to do that in our prime number programs, we are going to use C library functions that obtain the current time, and use it as a stopwatch: we'll grab the time just before starting processing, and then once more when done. The total time will then be the difference between the two (end_time - start_time).

We are going to use the **gettimeofday(2)** function to aid us in this, and to use it, we'll need to do the following:

====header file====
In order to use the **gettimeofday(2)** function in our program, we'll need to include the **sys/time.h** header file, so be sure to add it in with the existing ones:

<code c>
#include <stdio.h>
#include <stdlib.h>
#include <sys/time.h>
</code>

====timeval variables====
**gettimeofday(2)** uses a **struct timeval** data type, of which we'll need to declare two variables in our programs (one for storing the starting time, and the other for the ending time).

Please declare these with your other variables, up at the top of main() (but still WITHIN main()-- you do not need to declare global variables).

<code c>
    struct timeval time_start; // starting time
    struct timeval time_end;   // ending time
</code>

====Obtaining the time====
To use **gettimeofday(2)**, we merely place it at the point in our code we wish to take the time.

For our prime number programs, you'll want to grab the start time **AFTER** you've declared variables and processed arguments, but **JUST BEFORE** starting the driving loop doing the processing.

That call will look something like this:

<code c>
    gettimeofday(&time_start, 0);
</code>

The ending time should be taken immediately after all processing (and prime number output) is completed, and right before we display the timing information to STDERR:

<code c>
    gettimeofday(&time_end, 0);
</code>

====Displaying the runtime====
Once we have the starting and ending times, we can display this to the **timing** file pointer. You'll want this line:

<code c>
fprintf(stderr, "%8.4lf\n",
time_end.tv_sec-time_start.tv_sec+((time_end.tv_usec-time_start.tv_usec)/1000000.0));
</code>

For clarity sake, that format specifier is "%8.4lf", where the "lf" is "long float", that is **NOT** a number 'one' but a lowercase letter 'ell'.

And with that, we can compute an approximate run-time of our programs. The timing won't necessarily be accurate down to that level of precision, but it will be informative enough for our purposes.

=====Loops=====
A loop is basically instructing the computer to repeat a section, or block, or code a given amount of times (it can be based on a fixed value-- repeat this 4 times, or be based on a conditional value-- keep repeating as long as (or while) this value is not 4).

Loops enable us to simplify our code-- allowing us to write a one-size-fits all algorithm (provided the algorithm itself can appropriately scale!), where the computer merely repeats the instructions we gave. We only have to write them once, but the computer can do that task any number of times.

Loops can be initially difficult to comprehend because unlike other programmatic actions, they are not single-state in nature-- loops are multi-state. What this means is that in order to correctly "see" or visualize a loop, you must analyze what is going on with EACH iteration or cycle, watching the values/algorithm/process slowly march from its initial state to its resultant state. Think of it as climbing a set of stairs... yes, we can describe that action succinctly as "climbing a set of stairs", but there are multiple "steps" (heh, heh) involved: we place our foot, adjust our balance-- left foot, right foot, from one step, to the next, to the next, allowing us to progress from the bottom step to the top step... that process of scaling a stairway is the same as iterating through a loop-- but what is important as we implement is what needs to happen each step along the way.

With that said, it is important to be able to focus on the process of the individual steps being taken. What is involved in taking a step? What constitutes a basic unit of stairway traversal? If that unit can be easily repeated for the next and the next (and in fact, the rest of the) steps, we've described the core process of the loop, or what will be iterated a given number of times.

In C and C-syntax influenced languages (C++, Java, PHP, among others), we typically have 3 types of loops:

  * **for** loop (automatic counter loop, stepping loop; top-driven) - when we know exactly how many times we wish something to run; we know where we want to start, where we want to end, and exactly how to progress from start to end (step value)
  * **while** loop (top-driven conditional loop) - when we want to repeat a process, but the exact number of iterations is either not known, not important, not known, or variable in nature. While loops can run 0 or more times.
  * **do-while** loop (bottom-driven conditional loop) - similar to the while loop, only we do the check for loop termination at the bottom of the loop, meaning it runs 1 or more times (a do-while loop is guaranteed to run at least once).

====for() loops====
A **for()** loop is the most syntactically unique of the loops, so care must be taken to use the proper syntax.

With any loop, we need (at least one) looping variable, which the loop will use to analyze whether or not we've met our looping destination, or to perform another iteration.

A for loop typically also has a defined starting point, a "keep-looping-while" condition, and a stepping equation.

Here's a sample for() loop, in C, which will display the squares of each number, starting at 0, and stepping one at a time, for 8 total iterations:

<code c>
int i = 0;

for (i = 0; i < 8; i++)
{
    fprintf(stdout, "loop #%d ... %d\n", (i+1), (i*i));
}
</code>

The output of this code, with the help of our loop should be:

<cli>
loop #1 ... 0
loop #2 ... 1
loop #3 ... 4
loop #4 ... 9
loop #5 ... 16
loop #6 ... 25
loop #7 ... 36
loop #8 ... 49
</cli>

Note how we can use our looping variable (**i**) within mathematical expressions to drive a process along... loops can be of enormous help in this way.

And again, we shouldn't look at this as one step-- we need to see there are 8 discrete, distinct steps happening here (when i is 0, when i is 1, when i is 2, ... up until (and including) when i is 7).

The loop exits once **i** reaches a value of 8, because our loop determinant condition states as long as **i** is **less than** **8**, continue to loop. Once **i** becomes **8**, our looping condition has been satisfied, and the loop will no longer iterate.

The stepping (that third) field is a mathematical expression indicating how we wish for **i** to progress from its starting state (of being equal to 0) to satisfying the loop's iterating condition (no longer being less than 8).

**i++** is a shortcut we can use in C; the longhand (and likely more familiar) equivalent is: **i = i + 1**

====while() loops====
A **while()** loop isn't as specific about starting and stepping values, really only caring about what condition needs to be met in order to exit the loop (keep looping while this condition is true).

In actuality, anything we use a for loop for can be expressed as a while loop-- we merely have to ensure we provide the necessary loop variables and progressions within the loop.

That same loop above, expressed as a while loop, could look like:

<code c>
int i = 0;

while (i < 8)
{
    fprintf(stdout, "loop #%d ... %d\n", (i+1), (i*i));
    i = i + 1;   // I could have used "i++;" here
}
</code>

The output of this code should be identical, even though we used a different loop to accomplish the task (try them both out and confirm!)

**while()** loops, like **for()** loops, will run 0 or more times; if the conditions enabling the loop to occur are not initially met, they will not run... if met, they will continue to iterate until their looping conditions are met.

It is possible to introduce a certain kind of **logical error** into your programs using loops-- what is known as an "infinite loop"; this is basically where you erroneously provide incorrect conditions to the particular loop used, allowing it to start running, but never arriving at its conclusion, thereby iterating forever.

Another common **logical error** that loops will allow us to encounter will be the "off by one" error-- where the conditions we pose to the loop are incorrect, and the loop runs one magnitude more or less than we had intended. Again, proper debugging of our code will resolve this situation.

====do-while loops====
The third commonly recognized looping structure in C, the do-while loop is identical to the while() (and therefore also the for()) loop, only it differs in where it checks the looping condition: where **for()** and **while()** are "top-driven" loops (ie the test for loop continuance occurs at the top of the loop, **before** running the code in the loop body), the **do-while** is a "bottom-driven" loop (ie the test for loop continuance occurs at the bottom of the loop).

The placement of this test determines the minimal number of times a loop can run.

In the case of the for()/while() loops, because the test is at the top- if the looping conditions are not met, the loop may not run at all. It is for this reason why these loops can run "0 or more times"

For the do-while loop, because the test occurs at the bottom, the body of the loop (one full iteration) is run before the test is encountered. So even if the conditions for looping are not met, a do-while will run "1 or more times".

That may seem like a minor, and possibly annoying, difference, but in nuanced algorithm design, such distinctions can drastically change the layout of your code, potentially being the difference between beautifully elegant-looking solutions and those which appear slightly more hackish. They can BOTH be used to solve the same problems, it is merely the nature of how we choose express the solution that should make one more preferable over the other in any given moment.

I encourage you to intentionally try your hand at taking your completed programs and implementing other versions that utilize the other types of loops you haven't utilized. This way, you can get more familiar with how to structure your solutions and express them. You will find you tend to think in a certain way (from experience, we seem to get in the habit of thinking "top-driven", and as we're unsure, we tend to exert far more of a need to control the situation, so we tend to want to use **for** loops for everything-- but practicing the others will free your mind to craft more elegant and efficient solutions; but only if you take the time to play and explore these possibilities).

So, expressing that same program in the form of a do-while loop (note the changes from the while):

<code c>
int i = 0;

do
{
    fprintf(stdout, "loop #%d ... %d\n", (i+1), (i*i));
    i = i + 1;  // again, we could just as easily use "i++;" here
} while(i < 8);
</code>

In this case, the 0 or more vs. 1 or more minimal iterations wasn't important; the difference is purely syntactical.

With the do-while loop, we start the loop with a **do** statement.

Also, the do-while is the only one of our loops which NEEDS a terminating semi-colon (**;**).. please take note of this.

=====Execution=====

====specified quantity====
Your program output should be as follows (given the specified quantity):

<cli>
lab46:~/src/cprog/pnc0$ ./primereg 24 1
2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 
  0.0001
lab46:~/src/cprog/pnc0$ 
</cli>

The execution of the programs is short and simple- grab the parameters, do the processing, produce the output, and then terminate.

====invalid lower bound====
Here's an example that should generate an error upon running (based on project specifications):

<cli>
lab46:~/src/cprog/pnc0$ ./primereg 32 1 0
./primereg: invalid lower bound
lab46:~/src/cprog/pnc0$ 
</cli>

In this case, the program logic should have detected an invalid condition and bailed out before prime computations even began. No timing data is displayed, because exiting should occur even prior to that.

====upper bound overriding quantity====
As indicated above, there is potential interplay with an active quantity and upper bound values. Here is an example where upper bound overrides quantity, resulting in an early termination (ie upper bound is hit before quantity):

<cli>
lab46:~/src/cprog/pnc0$ ./primereg 128 1 7 23
7 11 13 17 19 23
  0.0001
lab46:~/src/cprog/pnc0$ 
</cli>

Also for fun, I set the lower bound to 7, so you'll see computation starts at 7 (vs. the usual 2).

=====Check Results=====
If you'd like to compare your implementations, I rigged up a Makefile checking rule called "**make checkqty**" and "**make checkrange**" which you can run to get a nice side-by-side runtime comparisons of your implementations.

In order to work, you **MUST** be in the directory where your pnc0 binaries reside, and must be named as such (which occurs if you ran **make** to compile them).

====check qty====
For instance (running on my implementation of the pnc0 programs, some output omitted to keep the surprise alive):

<cli>
lab46:~/src/cprog/pnc0$ make checkqty
=================
      qty     reg
=================
       32  0.0002
       64  0.0006
      128  0.0028
      256  0.0123
      512  0.0574
     1024  0.2690
...
   262144  ------
=================
 verify:     OK  
=================
lab46:~/src/cprog/pnc0$ 
</cli>

====check range====
Or check range runtimes:

<cli>
lab46:~/src/cprog/pnc0$ make checkrange
=================
    range     reg
=================
       32  0.0001
       64  0.0001
      128  0.0002
      256  0.0004
      512  0.0015
     1024  0.0053
     2048  0.0191
     4096  0.0709
     8192  0.2712
...
  2097152  ------
=================
 verify:     OK 
=================
lab46:~/src/cprog/pnc0$ 
</cli>

If the runtime of a particular prime variant exceeds an upper runtime threshold (likely to be set at 1 second), it will be omitted from further tests, and a series of dashes will instead appear in the output.

If you don't feel like waiting, simply hit **CTRL-c** (maybe a couple of times) and the script will terminate.

====Verification====
I also include a validation check- to ensure your prime programs are actually producing the correct list of prime numbers. If the check is successful, you will see "OK" displayed beneath in the appropriate column; if unsuccessful, you will see "MISMATCH".

====Full Verification Compliance====
There's also a more rigorous verification step you can take, which runs your programs through a series to tests to see if they conform to project specifications:

<cli>
lab46:~/src/cprog/pnc0$ make verifyall
=================
              reg
=================
 qtynorm:    OK  
 qtypart:    OK  
 rngnorm:    OK  
 rngpart:    OK  
    coop:    OK  
   coop2:    OK  
   coop3:    OK  
  noargs:    OK  
 invargs:    OK  
  invqty:    OK  
 invnary:    OK  
  invlow:    OK  
 invhigh:    OK  
=================
lab46:~/src/cprog/pnc0$ 
</cli>

===verifyall tests===
The "**verifyall**" is an industrial grade verification; there are 13 specific tests performed, they are:
  * **qtynorm**: a normal quantity run (2-max)
    * **./primealg 2048 1 2 0**
  * **qtypart**: an offset quantity run (24-max)
    * **./primealg 2048 1 24 0**
  * **rngnorm**: a normal range run (2-max)
    * **./primealg 0 1 2 2048**
  * **rngpart**: an offset range run (24-max)
    * **./primealg 0 1 24 2048**
  * **coop**: both qty and upper bounds set (q: 2048, ub: 8192)
    * **./primealg 2048 1 2 8192**
  * **coop2**: both qty and upper bounds set (q: 512, ub: 8192)
    * **./primealg 512 1 2 8192**
  * **coop3**: both qty and upper bounds set, offset start (24-max, q: 2048, ub: 8192)
    * **./primealg 2048 1 24 8192**
  * **noargs**:  no arguments provided on command line (invokes error message)
    * **./primealg**
  * **invargs**: insufficient number of arguments provided (invokes error)
    * **./primealg 128**
  * **invqty**: invalid value for quantity argument given (invokes error)
    * **./primealg -2 1**
  * **invnary**: invalid value given for n-ary (invokes error)
    * **./primealg 128 2**
  * **invlow**: invalid value given for lower bound (invokes error)
    * **./primealg 128 1 1**
  * **invhigh**: invalid value given for upper bound (invokes error)
    * **./primealg 128 1 32 24**

If you'd actually to see the output your program's output is being tested against, that can be found in the **/usr/local/etc** directory in the file **primeTEST**, where "TEST" is the name of the verify test mentioned above.

For example, if you wanted to see the intended output of the **invnary** test, that would be found in:

  * **/usr/local/etc/primeinvnary**

You could easily run your program with the stated arguments for the test, then use **cat** to display the test results and do a visual comparison.
====In general====
Analyze the times you see... do they make sense, especially when comparing the algorithm used and the quantity being processed? These are related to some very important core Computer Science considerations we need to be increasingly mindful of as we design our programs and implement our solutions. Algorithmic complexity and algorithmic efficiency will be common themes in all we do.

=====Submission=====
To successfully complete this project, the following criteria must be met:

  * Code must compile cleanly (no warnings or errors)
  * Output must be correct, and match the form given in the sample output above.
  * Code must be nicely and consistently indented (you may use the **indent** tool)
  * Code must utilize the algorithm(s) presented above:
    * **primereg.c** must do the raw, unoptimized brute force method
  * Code must be commented
    * have a properly filled-out comment banner at the top
      * be sure to include any compiling instructions
    * have at least 20% of your program consist of **<nowiki>//</nowiki>**-style descriptive comments
  * Output Formatting (including spacing) of program must conform to the provided output (see above).
  * Track/version the source code in a repository
  * Submit a copy of your source code to me using the **submit** tool.

To submit this program to me using the **submit** tool, run the following command at your lab46 prompt:

<cli>
lab46:~/src/cprog/pnc0$ make submit
removed ‘primereg’
removed ‘errors’

Project backup process commencing

Taking snapshot of current project (pnc0)      ... OK
Compressing snapshot of pnc0 project archive   ... OK
Setting secure permissions on pnc0 archive     ... OK

Project backup process complete

Submitting cprog project "pnc0":
    -> ../pnc0-20171018-16.tar.gz(OK)

SUCCESSFULLY SUBMITTED
</cli>

You should get that final "SUCCESSFULLY SUBMITTED" with no error messages occurring. If not, check for typos and or locational mismatches.

====Evaluation Criteria====
Grand total points:

<code>
78:pnc0:final tally of results (78/78)
</code>

What I will be looking for (for each file):

<code>
*:pnc0:primeALGO.c compiles cleanly, no compiler messages [9/9]
*:pnc0:primeALGO.c implements only specified algorithm [11/11]
*:pnc0:primeALGO.c consistent indentation throughout code [9/9]
*:pnc0:primeALGO.c relevant comments throughout code [9/9]
*:pnc0:primeALGO.c code conforms to project specifications [9/9]
*:pnc0:primeALGO.c runtime output conforms to specifications [6/6]
*:pnc0:primeALGO.c make checkqty test times within reason [6/6]
*:pnc0:primeALGO.c make checkrange test times within reason [6/6]
*:pnc0:primeALGO.c make verifyall tests succeed [13/13]
</code>

As the optimizations improve upon others, some evaluations will be based upon differences between a baseline (in some cases, primereg) and the optimization.
Lab46 Wiki

User Tools

Site Tools

Page Tools
