Initial commit

Author: fruzsinaagocs

.github/workflows/python-package.yml

@@ -0,0 +1,40 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python package
+
+on:
+  push:
+    branches: [ "main", "gh-actions-demo" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        python -m pytest

README.md

@@ -0,0 +1,64 @@
+# Git and GitHub tutorial
+
+## 1. Contributing to a project with no direct access (via a fork)
+
+1. Create a fork of the repository on GitHub: click on the "Fork" button to the right of this repository
+2. Navigate to your fork of the repository on GitHub
+3. Create a local copy of your fork: in the terminal, 
+```bash
+git clone git@github.com:<your username>/git-tutorial-2025>
+```
+4. Now you have a local copy of this repo! Make some changes. Correct your name in the "students.txt" file (on your machine, not on GitHub).
+5. Add the file to the upcoming commit from the terminal: `git add students.txt`
+6. Add a useful message that summarizes your changes: `
+```bash
+git commit -m "<summary>"
+```
+7. Push your changes from your local environment to your fork on GitHub: 
+```bash
+git push [--set-upstream ...]
+```
+8. Create a pull request to the original repository (that you forked). We will review and merge them.
+
+## 2. Contributing to a project directly 
+
+1. Change directory (`cd`) into `cu-comptools` on your machine, since you already have a copy from submitting homework.
+2. Git clone _this_ repository directly (not your fork of it!): 
+```bash
+git clone git@github.com:cu-comptools/git-tutorial-2025
+```
+Unlike a fork, this creates a local copy of the repository itself, not your fork of it, so any changes you make and push would directly change the repository. So it's best to proceed from here with caution and use best practices when making changes: creating a new branch with the changes and then submitting a pull request into the main branch.
+3. Bug fix exercise: create a new branch, `git checkout -b quadfix-<your name>`. Take a look at the code `utils/quadroots.py` (or `utils/quadroots.m` if you're working in MATLAB), which contains a bug. Fix this bug. 
+
+To test whether you successfully fixed the bug, you will try running the unit test I wrote. In Python, this will be done via `pytest` (which you may have to install via conda or pip). In MATLAB, it'll be done by running the function without arguments, i.e. just executing the file. 
+
+In Python,
+```bash
+python -m pytest
+```
+
+4. Once the bug is fixed, commit your changes with `git commit` and a useful message. Either add a message directly in the command line with
+```bash
+git commit -m "<Very useful commit message>"
+```
+or set the default commit message editor to be your editor of choice:
+```bash
+git config --global core.editor "<your favorite editor, such as vim>"
+```
+
+5. When pushing, git will ask you to specify which remote you want to push to, with the `git push --set-upstream origin quadfix-<your-name>` command. This specifies that you want your repository on GitHub (the remote called "origin") to have a new branch with the same name as your local branch.
+6. Submit a pull request to the `main` branch. We'll review and merge later.
+
+## 3. Documentation exercise
+
+1. In the `utils/` directory, there's another `.py` (`.m`) file that implements a single function. It only has a hint in its docstring. Look up the source from the hint, read the code, and try to figure out what the function does.
+2. Write a docstring for this function.
+4. Create a new branch for your work with the name `docfix-<your name>`, push to the remote repository, and submit a pull request to the main branch.
+
+## 4. Unit test exercise
+
+1. In most projects, like this one, there will be a `tests/` directory housing unit tests. They will usually be executed automatically, most often even before the contribution gets merged (upon a pull request). If in Python, inspect `tests/test_utils.py`, if in MATLAB, take a look at how the self-test is executed in `utils/quadroots.m`. 
+2. Now take the function in `chebutils` and try to come up with a test case: is there a check you can devise for this function where you know the analytic answer? Code up your test input, your expected output from the function, and write a statement that takes the absolute or relative error between the expected answer an the output of a call of the function with the test arguments. Then come up with a resonable upper bound for this error, and put it in an `assert` statement. 
+3. Run the unit tests to see if they work (the function is guaranteed to be correct).
+4. As before, make a temporary new branch called `unittest-<your name>`, and submit a pull request with your unit test.
+

requirements.txt

@@ -0,0 +1,2 @@
+numpy
+pytest

students.txt

@@ -0,0 +1 @@
+

tests/test_utils.py

@@ -0,0 +1,15 @@
+import numpy as np
+from utils import quadroots as qr
+from utils import chebutils as ch
+
+def test_quadroots_1():
+    a = 2.0
+    b = -5.0
+    c = 2.0
+    roots = qr.quadroots(a, b, c)
+    x1_exact = 2.0
+    x2_exact = 0.5
+    assert (np.abs(roots[0] - x1_exact) < 1e-14) and (np.abs(roots[1] - x2_exact)) < 1e-14 
+
+def test_chebD_1():
+    pass

utils/__init__.py

@@ -0,0 +1,22 @@
+function [D, x] = cheb(n)
+%
+% Hint: https://people.maths.ox.ac.uk/trefethen/book.pdf, Chapter 6, pages
+% 51-55.
+% Without arguments, this function should do a self-check.
+%
+if nargin==0, test_cheb; return; end
+
+if n==0
+    x = 1;
+    D = 0;
+else
+    x = cos(pi*(0:n)/n)';
+    c = [2; ones(n-1, 1); 2].*(-1).^(0:n)';
+    x = repmat(x, 1, n+1);
+    dx = x - x';
+    D = (c*(1./c)')./(dx + (eye(n+1)));
+    D = D - diag(sum(D'));
+end
+
+%%%
+function test_cheb

utils/chebutils.m

@@ -0,0 +1,22 @@
+import numpy as np
+
+def chebD(n):
+    """
+    Hint: https://people.maths.ox.ac.uk/trefethen/book.pdf, Chapter 6, pages
+    51-55.
+    """
+    if n == 0:
+        x = 1; D = 0; w = 0
+    else:
+        a = np.linspace(0.0, np.pi, n+1)
+        x = np.cos(a)
+        b = np.ones_like(x)
+        b[0] = 2; b[-1] = 2
+        d = np.ones_like(b)
+        d[1::2] = -1
+        c = b*d
+        X = np.outer(x, np.ones(n+1))
+        dX = X - X.T
+        D = np.outer(c, 1/c) / (dX + np.identity(n+1))
+        D = D - np.diag(D.sum(axis=1))
+    return D, x

utils/chebutils.py

@@ -0,0 +1,33 @@
+function [x1, x2] = quadroots(a, b, c)
+% Calculates the roots of the quadratic equation 0 = a*x^2 + b*x + c, and
+% returns them as a tuple. If a root is repeated, the elements of the tuple
+% will be identical. 
+% If called without arguments, the function performs a self-test.
+% 
+% Parameters
+% ----------
+% a: float
+%     Coefficient of x^2 in the input equation.
+%  b: float
+%     Coefficient of x in the input equation.
+%  c: float
+%     Constant coefficient of in the input equation.
+% 
+%  Returns
+%  -------
+%  x1, x2: float
+%     Roots of the equation.
+if nargin==0, test_quadroots; return; end
+
+x1 = (-b + sqrt(b*b - 4*a*c))/2*a;
+x2 = (-b - sqrt(b*b - 4*a*c))/2*a;
+
+%%%
+function test_quadroots
+a = 2;
+b = -5;
+c = 2;
+[root1, root2] = quadroots(a, b, c);
+root1exact = 2;
+root2exact = 0.5;
+assert(abs(root1exact - root1) < 1e-14 && abs(root2exact - root2) < 1e-14);

utils/quadroots.m

@@ -0,0 +1,27 @@
+import numpy as np
+
+def quadroots(a, b, c):
+    """
+    Calculates the roots of the quadratic equation 0 = a*x^2 + b*x + c, and
+    returns them as a tuple. If a root is repeated, the elements of the tuple
+    will be identical. 
+    
+    Parameters
+    ----------
+    a: float
+        Coefficient of x^2 in the input equation.
+    b: float
+        Coefficient of x in the input equation.
+    c: float
+        Constant coefficient of in the input equation.
+
+    Returns
+    -------
+    (x1, x2): tuple<float>
+        Roots of the equation.
+    """
+
+    x1 = (-b + np.sqrt(b**2 - 4*a*c))/2*a
+    x2 = (-b - np.sqrt(b**2 - 4*a*c))/2*a
+
+    return (x1, x2)