Milestone 0

Assigned:	8/21
Due:	9/7 by 11:59 pm

Introduction

The goal of this first milestone is to familiarize yourself with plotscript, the starter code implementing the interpreter, and how to build and run its tests on your host machine as well as the reference environment. These will introduce you to the course work-flow and how to read and follow others code. This is a useful skill as projects you work on will rarely have no preexisting code. You will also add a complex numerical type to the language and implement related numerical procedures. This will ensure you have a reasonably good understanding of the starter code. The work is divided into four tasks to guide your work. You are encouraged to ask questions in class, on Piazza, during help sessions, or during office hours if you have questions about the provided code.

This assignment requires little C++ experience beyond basic data structures (e.g. memory management and trees). If you struggle with the programming part of this assignment you are woefully ill-prepared for this course. This means you should devote additional time to it and seek advice from the TAs and myself, or as a last resort drop.

Background Information

• Project Overview
• CMake Workflow on Windows
• Documentation for the starter code

Task 1: building the starter code

If you have not already, accept the GitHub invitation at this link and then clone the git repository to your local machine. The initial git repository contains the starter code for the semesters project. Be sure you can build the code, run the tests, and run the plotscript program on both your host machine and in the reference environment.

Steps to build and run the tests in the reference environment (after opening the Terminal emulator).

• To configure the build

  cmake /vagrant

• To run the build

  make

  or

  cmake --build .

• To run the unit tests

  make test

  or

  cmake --build . --target test

  The test output is placed in ``Testing/Temporary/LastTest.log. You can also just run the tests directly:

  ./unit_tests

• To configure and run the build in strict mode (increased warnings, warnings become errors)

  cmake -DSTRICT=True /vagrant
  make clean; make

Task 2: experimenting with the interpreter

To get a feel for the syntax of plotscript you should go though the following examples.

Example 1: Before typing in the code, what does the following code evaluate to?

(begin
    (define a 1)
    (define b 2)
    (define c (* 2 b))
    (- c (+ (/ 1 a) b))
)

Example 2: Using the plotscript REPL enter the same code above without the begin expression (one line at a time). Does the final result match your answer above.

Example 3: Create a file named example3 and write a plotscript program to find the average of the following numbers: 42, 34, 89, -3, 95, 4, -9, 32. Run your program using the plotscript program and verify the results are correct.

Task 3: extend procedures for the Number type

The operations of our Numbers type in the base language are limited. Your task is to understand how the environment and procedures are implemented in the C++ interpreter code and extend it as follows. You should implement them one at a time, making a commit to your repository with an appropriate message each time. This will give you practice with working in increments.

• Extend the built-in symbols to include the Number symbol e, defined as Euler's number, i.e. std::exp(1).
• Extend the procedures for Number to include the unary procedure sqrt, the square root. Temporarily, the procedure should throw a semantic exception for negative arguments -- for the extension to negative arguments see task 4.
• Extend the procedures for Number to include the binary procedure (^ a b), the exponential of a to the power b. Temporarily, the procedure should behave identical to std::pow -- for extensions see task 4.
• Extend the procedures for Number to include the unary procedure ln, the natural logarithm. The procedure should throw a semantic exception for negative arguments.
• Extend the procedures for Number to include the unary procedure sin, the trigonometric sine of the angle argument in radians.
• Extend the procedures for Number to include the unary procedure cos, the trigonometric cosine of the angle argument in radians.
• Extend the procedures for Number to include the unary procedure tan, the trigonometric tangent of the angle argument in radians.

Task 4: Adding a complex number type

Complex numbers are ubiquitous in engineering mathematics. Our current implementation of plotscript only supports real numbers modeled as double precision (IEEE 754) numbers. Extend the interpreter code to support complex numbers as the type Complex, using double precision numbers for the real and imaginary part as follows. As before, you should implement incremental changes, testing and making a commit to your repository with an appropriate message each time.

• Extend the built-in symbols to include the Complex symbol I, defined as the imaginary number, √ -1 = 0 + i.
• Extend the built-in m-ary procedure for addition to include both Numbers and Complex types. If any argument is complex, the result should be complex.
• Extend the built-in unary and binary procedures for subtraction to include both Numbers and Complex types. If any argument is complex, the result should be complex.
• Extend the built-in m-ary procedure for multiplication to include both Numbers and Complex types. If any argument is complex, the result should be complex.
• Extend the built-in binary procedure for division to include both Numbers and Complex types. If any argument is complex, the result should be complex.
• Add a built-in unary procedure real to return the real part of a Complex as a Number. It is a semantic error of the argument is not Complex.
• Add a built-in unary procedure imag to return the imaginary part of a Complex as a Number. It is a semantic error of the argument is not Complex.
• Add a built-in unary procedure mag to return the magnitude (absolute value) of a Complex as a Number. It is a semantic error of the argument is not Complex.
• Add a built-in unary procedure arg to return the argument (angle or phase) of a Complex as a Number in radians. It is a semantic error of the argument is not Complex.
• Add a built-in unary procedure conj to return the conjugate of a Complex argument. It is a semantic error of the argument is not Complex.
• Extend the procedure sqrt from task 1 to also return the square root of a Complex argument or a negative Number argument
• Extend the procedure ^ from task 1 to return the exponential of a to the power b for any combination of Number and Complex types on a and b. The result should be of type Number only when both arguments are of type Number.

When displaying a complex expression render it as (real,imag). For example:

plotscript> (I)
(0,1)

Examples

The following are a few examples to give you a better idea of the syntax specified.

(- I (sqrt -1))

should display (0,0).

(define x (+ 1 (* 2 I)))

defines the symbol x to be the complex number 1 + 2i. The real part of x is then (real x), the imaginary part is (imag x), while the magnitude and phase angle are (mag x) and (arg x) respectively.

(^ e (- (* pi I)))

computes a famous result due to Euler. Note the imaginary part might not be identically zero.

Submission

To submit your milestone:

1. Tag the git commit that you wish to be considered for grading as "milestone0".

   git tag milestone0

2. Push this change to GitHub

   git push origin milestone0

If you need to tag a different version of your code simply create and push a new tag appending a monotonically increasing number to milestone0 using '-', e.g. milestone0-2, milestone0-3, etc.

Be sure you have committed all the changes you intend to. You should re-clone your repository into a separate directory and double check it is what you intend to submit. Failure to complete these steps by the due date will result in a failed submission.

Grading

There are 6 course percentage points allocated to this milestone. You will receive a detailed feedback report on your submission via Canvas within two weeks of the due date.

Code compiles in the reference environment	1 point
Correctness Tests	4 points
Code Quality	0.5 point
Good Development Practices	0.5 point

Note, if your code does not build in the reference environment you will receive no points. Correctness can be checked in the auto-grader and is determined by the proportion of instructor tests that pass. The auto-grader uses the exact same environment as the reference so if your code compiles there, it should in the auto-grader as well. You are rate-limited to only two submissions every two hours to the auto-grader so as to prevent you from using it as your development environment and encourage proper debugging skills.