ReadMe File Examples

Thomas J. Kennedy

Contents:

1 C++ Example

2 Python Example

All code you submit must by accompanied by a Readme file, preferably in markdown format, and named README.md

For this course, you will need to include:

Any libraries your code requires (e.g., Boost)
Compilation instructions (for compile languages)
How to run your program
Sample output listing

1 C++ Example

A README.md for a C++ program would take a form similar to:

Example 1: C++ Markdown Source

# Requirements

  * g++ v5.4 or newer
  * Boost 1.58.0 or newer
    * The `boost/multiprecision/float128.hpp` header must be available
  * Make

## Installed Boost Packages

For development the following boost packages were installed.

```
libboost-date-time1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed]
libboost-filesystem1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed]
libboost-iostreams1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed]
libboost-python1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic]
libboost-regex1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic]
libboost-system1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed]
libboost-test-dev/xenial,now 1.58.0.1ubuntu1 amd64 [installed]
libboost-test1.58-dev/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic]
libboost-test1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic]
libboost1.58-dev/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic]
libboost1.58-doc/xenial-updates,xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 all [installed]
```

This listing was obtained by running `apt list --installed | grep boost`.


# Compilation

The code can be compiled with the provided makefile using the standard `make`
command.

If compiling the code manually, or integrating into a larger program, include
the following flags:

```
FLAGS=-std=c++17 -fsanitize=address -fuse-ld=gold -Wall -MMD \
      -fext-numeric-literals -lquadmath #-O3
```

Note that flag `-fuse-ld=gold` is only required on certain Ubuntu systems due
to a know bug with g++ 5.x.


# Sample Execution & Output

If run without command line arguments, using

```
./precisionEstimate
```

the following usage message will be displayed.

```
Usage: ./precisionEstimate numExecs
```

If run using 

```
./precisionEstimate 100000000
```

output *simliar* to

```
   0 secs | 1.19209e-07
   1 secs | 2.22045e-16
  17 secs | 1.92593e-34
```

will  be displayed. Note that the precision estimates will vary by
architecture/system.

If run through a markdown processor (e.g., in GitLab) this markdown would render as

Example 2: C++ Rendered Markdown

Requirements

g++ v5.4 or newer

Boost 1.58.0 or newer

The boost/multiprecision/float128.hpp header must be available

Make

Installed Boost Packages

For development the following boost packages were installed.

libboost-date-time1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed] libboost-filesystem1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed] libboost-iostreams1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed] libboost-python1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic] libboost-regex1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic] libboost-system1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed] libboost-test-dev/xenial,now 1.58.0.1ubuntu1 amd64 [installed] libboost-test1.58-dev/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic] libboost-test1.58.0/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic] libboost1.58-dev/xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 amd64 [installed,automatic] libboost1.58-doc/xenial-updates,xenial-updates,now 1.58.0+dfsg-5ubuntu3.1 all [installed]

This listing was obtained by running apt list --installed | grep boost.

Compilation

The code can be compiled with the provided makefile using the standard make command.

If compiling the code manually, or integrating into a larger program, include the following flags:

FLAGS=-std=c++17 -fsanitize=address -fuse-ld=gold -Wall -MMD \ -fext-numeric-literals -lquadmath #-O3

Note that flag -fuse-ld=gold is only required on certain Ubuntu systems due to a know bug with g++ 5.x.

Sample Execution & Output

If run without command line arguments, using

./precisionEstimate

the following usage message will be displayed.

Usage: ./precisionEstimate numExecs

If run using

./precisionEstimate 100000000

output simliar to

0 secs | 1.19209e-07 1 secs | 2.22045e-16 17 secs | 1.92593e-34

will be displayed. Note that the precision estimates will vary by architecture/system.

2 Python Example

A README.md for a Python program would take a form similar to:

Example 3: Python Markdown Source

# Requirements

  * Python 3.7

> This code makes use of the `f"..."` or [f-string
> syntax](https://www.python.org/dev/peps/pep-0498/). This syntax was
> introduced in Python 3.6.


# Sample Execution & Output

If run without command line arguments, using

```
./precisionEstimate
```

the following usage message will be displayed.

```
Usage: ./estimatePrecision.py num_execs [arbitrary precision]
```

If run using

```
./precisionEstimate 1000000
```

output *simliar* to

```
           float|  3.7247|2.220446049250313e-16
 float-type-hint|  3.6731|2.220446049250313e-16
      Decimal-28| 31.8602|0.999999999999999999999999999
```

will be generated. Note that the `float` and `float-type-hint` lines may vary.

---

An optional precision command line argument can be supplied to change the
arbitrary precision used by the Python `decimal` module. For example:

```
./precisionEstimate 1000000 16
```

will generate output similar to

```
           float| 0.3979|2.220446049250313e-16
 float-type-hint| 0.4053|2.220446049250313e-16
      Decimal-16| 3.1643|0.999999999999999
```

If run through a markdown processor (e.g., in GitLab) this markdown would render as

Example 4: Rendered Python Markdown

Requirements

Python 3.7

This code makes use of the f"..." or f-string syntax. This syntax was introduced in Python 3.6.

Sample Execution & Output

If run without command line arguments, using

./precisionEstimate

the following usage message will be displayed.

Usage: ./estimatePrecision.py num_execs [arbitrary precision]

If run using

./precisionEstimate 1000000

output simliar to

float| 3.7247|2.220446049250313e-16 float-type-hint| 3.6731|2.220446049250313e-16 Decimal-28| 31.8602|0.999999999999999999999999999

will be generated. Note that the float and float-type-hint lines may vary.

An optional precision command line argument can be supplied to change the arbitrary precision used by the Python decimal module. For example:

./precisionEstimate 1000000 16

will generate output similar to

float| 0.3979|2.220446049250313e-16 float-type-hint| 0.4053|2.220446049250313e-16 Decimal-16| 3.1643|0.999999999999999