Introduction to Git/GitHub (25 points)

Overview

In this assignment, students will work independently to gain an introduction to version control with Git, manage code using GitHub, and leverage GitHub Classroom for coursework submission. The assignment also serves as a refresher on writing and managing C/C++ code. Starting from the skeleton code, students will independently implement the calculation of π using the Monte Carlo method. Additionally, they will create a Makefile to compile their program and ensure that the code runs correctly on one of the UIC Systems machines.

Objective and Expected Learning Outcomes

The primary objectives of this assignment are:

  • To independently learn and practice the basics of Git and GitHub, including repository setup, cloning, and committing changes.
  • To apply programming skills in C/C++ by implementing a mathematical algorithm from a provided skeleton codebase.
  • To develop a Makefile for compiling and managing the program build process.
  • To verify the completed program works correctly on UIC Systems machines without external dependencies or collaboration.

Outcomes:

  1. Version Control Proficiency:
    • Independently demonstrate fundamental Git operations such as cloning, committing, and pushing code to a personal GitHub repository.
  2. Programming Skills in C/C++:
    • Write, debug, and enhance C/C++ code to implement the Monte Carlo method for approximating π from a provided skeleton codebase.
    • Adhere to best practices for clean, efficient, and maintainable coding.
  3. Build Management:
    • Create and utilize a Makefile to automate the compilation process effectively.
    • Understand the role of a Makefile in building code and managing dependencies.
  4. System Compatibility:
    • Ensure the final program runs seamlessly on UIC CS resources (systems{1-4}.cs.uic.edu) machines without modification.
    • Address potential issues specific to the target environment independently.
  5. Mathematical and Computational Application:
    • Apply the Monte Carlo method to estimate the value of π and understand its computational principles and accuracy limitations.
  6. Independent Problem-Solving:
    • Develop problem-solving and debugging skills by working through the assignment without collaboration or external help.
    • Demonstrate self-reliance in managing tasks and meeting assignment requirements.

Instructions

  1. Check out the code from a Git repository; you will make all changes to pi.cc.

  2. You will be given a link to an invitation for this assignment generated by GitHub Classroom; copy the link to a browser to accept the assignment. It will look something like this:

    https://classroom.github.com/a/<alphanumeric code>

    Clicking the link takes you to a page asking if you wish to accept this assignment. Ensure you read the message carefully to confirm it says something similar to the following:

     UIC-HPC
 Accept the assignment — 
 <XXXX>

 Once you accept this assignment, you will be granted access to the <XXXX>-<yourGitHubID> repository in 	the UIC-HPC organization on GitHub.

    The key thing you want to look for is that your GitHub ID is after the dash in the specified repository. If not automatically prompted, find and use the sign-in button on the upper right-hand side to log in. If you use a shared computer (i.e., lab computer), the browser may cache someone else login name. You can address this by clearing the browser cache and ensuring you are logged into GitHub in another tab in the same browser. If you still have problems, let your instructor and TA know ASAP. DO NOT ACCEPT ASSIGNMENT IF LOGIN NAME IS WRONG!!!!

    After accepting, the system will take you to a page displaying something similar to the following:

     You accepted the assignment, <XXXX>. We're configuring your repository now. This may take a few 	minutes to complete. Refresh this page to see updates.
 Your assignment is due by <Month> <Day>, <Year>, <Time> CST

 **Note:** You may receive an email invitation to join UIC-HPC on your behalf. No further action is 	necessary.
    • Depending on where you do your development, you can either click on the link and work from your browser or use command line tools as demonstrated in class. Either way, you will need eventually to generate a local repository. You should use one of the public CS resources, such as systems{1-4}.cs.uic.edu, to get used to working remotely, which you will need to do once we move to the HPC systems.

  3. You will then complete the assignment as follows:

    • Add the following doc-box comment to your local repository and commit the changes. Then, push the modifications to the remote repository. Modify the comment to include your name, the assignment you are working on, and its due date. Place this comment at the top of every file you modify this semester. Including this comment will contribute to a higher grade on the assignment.
     /*
 	<Your Name>
 	<Assignment>
 	<Date>

 	I certify that this is my work and, where appropriate, an extension of the starter code provided 		for the assignment.
 */
    • You will then implement the following pseudo code within the file pi.cc; you will then commit this change to your local repository, then push the change to the remote repository.
     # Function: calculatePi
 INPUT: num_points (Number of random points to generate)

 SET circle_count to 0  # Counter for points inside the unit circle
 CALL random number generator initialization with current time as seed

 FOR each point in the range from 1 to num_points
 	OBTAIN random x coordinate in the range [-1, 1]
 	OBTAIN random y coordinate in the range [-1, 1]
    
 	COMPUTE distance as (x^2 + y^2)
 	IF distance <= 1 THEN
     	INCREMENT circle_count
 	END IF
 END FOR

 COMPUTE pi_estimate as 4 * (circle_count / num_points)
 RETURN pi_estimate

    ### Notes:

    • The Monte Carlo method works by simulating random points in a square and counting how many fall inside the quarter-circle inscribed within that square.
    • The ratio of points inside the circle to the total points, scaled by 4, provides an approximation of π.

    • Random points are generated using a uniform distribution for x and y coordinates.

    • You will then create a Makefile for this assignment, generating a Makefile that compiles and builds an executable named introduction. The Makefile must produce an introduction by executing the command make.

    • You will now add the Makefile to your local repository, commit changes, and push to the remote repository.

  4. You will execute the make command, correct any compiler errors, commit changes, and push to the remote repository. If during the make you get an error Makefile:19: *** missing separator. Stop. this is likely due to cut and paste where the <tab> required by make is replaced with <spaces>.

  5. You will create a text file in your repository pi.txt where you write a sentence or two about the experience and answer the iterations needed to calculate pi to five significant digits (3.1416).

Submission Guidelines and Evaluation Criteria

  • When your program is ready for grading, commit and push your local repository to the remote git classroom repository and follow the Assignment Submission Instructions.

  • You will be evaluated on your ability to follow instructions, correctly name files, quality and completeness of code, and reflection on the assignment.

Additional Resources

Geeks for Geeks - Estimating Pi using Monte Carlo Method

Starter Code

main.cc

/* Added needed headers */

/**
 * @brief Estimates the value of π using the Monte Carlo method.
 *
 * @param num_points The number of random points to generate.
 * @return The estimated value of π.
 */
double calculatePi(int num_points) {
    
	return pi_estimate;
}

/**
 * @brief The main function to execute the program.
 *
 * @param argc The number of command-line arguments.
 * @param argv An array of command-line arguments.
 * @return 0 if the program runs successfully, or 1 if an error occurs.
 */
int main(int argc, char* argv[]) {
    // Check if the correct number of arguments is provided
    if (argc != 2) {
        // Print usage instructions if arguments are missing
        std::cerr << "Usage: " << argv[0] << " <number_of_points>" << std::endl;
        return 1; // Return error code
    }

    // Convert the second command-line argument to an integer
    int num_points = std::atoi(argv[1]);

    // Validate that the input is a positive integer
    if (num_points <= 0) {
        std::cerr << "Error: Number of points must be a positive integer." << std::endl;
        return 1; // Return error code
    }

    // Call the function to calculate π
    double pi = calculate_pi(num_points);

    // Output the estimated value of π
    std::cout << "Estimated value of π using " << num_points << " points: " << pi << std::endl;

    return 0; // Indicate successful program termination
}

Makefile

# Define the C++ compiler to use
CXX = g++

# Define any compile-time flags
CXXFLAGS = -std=c++14 -Wall -Wextra -pedantic -Wno-unused-parameter

# Define the C++ source files
SOURCES = pi.cc

# Define the C++ object files
OBJECTS = $(SOURCES:.cc=.o)

# Define the executable file 
MAIN = pi

.PHONY: all clean

all: $(MAIN)
	@echo Congratulations $(MAIN) has been compiled!

$(MAIN): $(OBJECTS)
	$(CXX) $(CXXFLAGS) -o $(MAIN) $(OBJECTS)

.cc.o:
	$(CXX) $(CXXFLAGS) -c $<  -o $@

clean:
	$(RM) *.o *~ $(MAIN)