Differences between revisions 19 and 53 (spanning 34 versions)
Revision 19 as of 2014-09-22 08:42:00
Size: 6652
Editor: khellman
Comment:
Revision 53 as of 2023-03-21 14:50:04
Size: 1638
Editor: khellman
Comment: correct submission template anchor
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
#acl _Students:read #acl All:read
Line 5: Line 5:
All simulation programming projects must meet these requirements. All simulation programming projects must meet these requirements on a standard student account of a CTB60 ("alamode") machine.
Line 7: Line 7:
 1. Submitted as a `.zip` or `.tar.(Z|gz|bz2)` compressed archive.
 {{{#!wiki warning
If you are generating an archive with symbolic links from another `*nix` box, just use `tar` --- the invocation of `zip` seems to be tricky (or there are inconsistent `zip` versions in Linux land).
 }}}
 1. The unrolled archive will be scanned for a '''top-most''' key file: '''only one of these may exist''':
    a. A `Makefile` compatible with [[http://www.gnu.org/software/make/|GNU make]] (this is the standard `make` on a Linux box)
    a. A `Build.sh` Bourne (`sh`) or `bash` script
    {{{#!wiki important
Case in names are important! It is `Makefile` with a capital `M`, not `makefile`; likewise for `Build.sh`.
This is a 400 level course in a CS program, I think it is reasonable to expect students to be able to either
 1. develop in a Unix environment
 1. transport a system independent code base<<FootNote(Sims should be pretty OS agnostic)>> from Windows or MacOS X to a Unix environment.
<<Include(SubmissionRequirements)>>
Line 20: Line 9:
If you need help doing this '''please let me know,''' I'm happy to assist.
    }}}
= Examples =
<<Anchor(SubmissionTemplates)>>
<<Include(SubmissionTemplates)>>
Line 23: Line 13:
 In either case, after running<<FootNote(The name of your directory containing `Makefile` or `Build.sh` does not have to be named `top`, the example is simply showing that `make` and `bash` will be run from ''within'' your top directory.)>>
 {{{
top $ make
 }}}
 or
 {{{
top $ bash Build.sh
 }}}
 there should be an application<<FootNote(This means the [[http://en.wikipedia.org/wiki/Filesystem_permissions#Permissions|Unix executable bit]] is set.)>> named `SIM` that is your simulator for the assignment.<<FootNote(This does not preclude `SIM` existing before `make` or `Build.sh` are run, and [[attachment:PlaceholderBuild.sh|a build script]] might be a mere placeholder. Such a setup is applicable for certain languages.)>> That's all capitals, `SIM`.
 1. `SIM` will be invoked with the appropriate command line arguments for the assignment, results required by the assignment should be printed on `stdout`. Any output line with an assignment required result '''must''' have `OUTPUT` as the first word (token).
 1. All numerical values required by an assignment must have whitespace (which includes end of line) around them.
 1. Required textual output should be surrounded by single colons (`:`).
 1. The '''order''' for results is assignment specific and '''important''', they must emanate from the application in the order dictated by the assignment.
 1. Your submitted archive should '''not''' contain unnecessary files (`.o`, `.pyc`, `*.h~`, ...). This includes `java` class files.
 1. Files and directories that begin with an '''underscore''' are reserved for use by your instructor, TA, or grader.
   a. Your submitted archive file should not have any entries that begin with an underscore.
   a. Your `SIM` should not use or create files or directories that begin with an underscore.
 1. Written answers or graphs should always be provided in a `doc` subdirectory, the `doc` directory should be alongside your `Makefile` or `Build.sh`, which is to say in your "top" directory.
   a. Prose should be provided in either a text file, an HTML file, or a PDF file.
   a. Graphs may be embedded in your written answers (if you provide HTML or PDF). If your answers are written in a simple text file, provide your graphs in a common raster image file format (PNG, JPEG, ...), SVG, or (preferably) PDF. Refer to the graphs by name in your answer write-up.
   a. Graphs provided for assignments without a required written component should be in appropriately named files (still, of course in `doc`) and should be self-explanatory on viewing.<<FootNote(Heaven forbid, don't forget a graph title.)>>
   a. Students may always feel free to submit a `README` file for any assignment, but it needs to be in `doc` and follow these conventions.


== Examples ==
=== Submission Templates ===
Here are example trees for submissions, one each for the most common languages used by students. If you are using another language, look at one of the templates for a similar language.
/* * [[attachment:submit-c.zip|C language]] */
 * [[attachment:submit-c++.zip|C++ language]]
 * [[attachment:submit-java.zip|Java language]]
 * [[attachment:submit-python.zip|Python language]]
 * [[attachment:submit-python3.zip|Python3 language]]
 * [[attachment:submit-ruby.zip|Ruby (1.9) language]]
== Output Formatting ==
Suppose a simulation assignment dictates:
Line 58: Line 17:
Templates with a `Makefile`: edit `Project.mak` instead --- much easier.   1. Your `SIM` should accept two arguments. The first argument is the seed for your pRNG, the second argument is the number of experimental runs.

  1. Your `SIM` should display 3 numerical results: the average `theta`, the minimum `theta`, and the median `alpha` across all the experimental runs.
Line 60: Line 21:

If like to use IDEs such as Eclipse or M$``Vs:
 1. do your work in the IDE with a simple source layout
 1. copy your code into the appropriate extracted template on `alamode`
 1. '''test''' to make sure it builds and runs correctly
 1. clean it out (there is a `clean` target in the provided Makefiles, otherwise remove residual files by hand)
 1. `tar` or `zip` it up and submit.

If your IDE purports to generate Makefiles, then give it a try (YMMV). Be sure to '''test on `alamode`'''.

{{{#!wiki warning

Beware that M$ based IDEs frequently generate `NMAKE` files, which are a far cry from conventional Unix `make` compatible build files, and are uniformly mocked by `gmake`.

}}}

=== Output Formatting ===
Suppose a simulation assignment dictates:

  Your `SIM` should accept two arguments. The first argument is the seed for your pRNG, the second argument is the number of experimental runs.

  Your `SIM` should display 3 numerical results: the average `theta`, the minimum `theta`, and the median `alpha` across all the experimental runs.

All simulation programming projects must meet these requirements on a standard student account of a CTB60 ("alamode") machine.

Requirements

  1. Submitted as a .zip or .tar.(Z|gz|bz2|xz) compressed archive. Do not use RAR archives.

    If you are generating an archive with symbolic links from another *nix box, just use tar --- the invocation of zip seems to be tricky (or there are inconsistent zip versions in Linux land).

  2. The unrolled archive will be scanned for a top-most key file: only one of these may exist:

    1. A Makefile compatible with GNU make (this is the standard make on a Linux box)

    2. A Build.sh Bourne (sh) or bash script

      Case in names are important! It is Makefile with a capital M, not makefile; likewise for Build.sh. This is a 400 level course in a CS program, I think it is reasonable to expect students to be able to either

      1. develop in a Unix environment
      2. transport a system independent code base1 from Windows or MacOS X to a Unix environment.

      If you need help doing this please let me know, I'm happy to assist.

    In either case, after running2

    top $ make
    or
    top $ bash Build.sh

    there should be an application3 named SIM. 4 Note that SIM is always in all capital letters.

  3. Your submission must build without extra installs of additional packages or libraries to the grader's account. The only exceptions to this requirement are the Python graphvis package and some select student favored languages: rust, go, lua, .NET. See this page for details about using one of these languages.

  4. SIM will be invoked with the appropriate command line arguments for the assignment, results required by the assignment should be printed on stdout.

    1. Any stdout output line with a required result must have OUTPUT as the first word (token).

    2. All numerical values required by an assignment must have whitespace (which includes end of line) around them.
    3. Required textual output should be surrounded by single colons (:).

    4. The order for results is assignment specific and important, they must emanate from the application in the order dictated by the assignment.

    5. Depending on the assignment, SIM may be required to write a specifically formatted result file, in which case the OUTPUT rules above won't apply to the contents of the file.

  5. Your submitted archive should not contain unnecessary files (.o, .pyc, *.h~, Cargo.lock ) or executable machine or vm code (*.class files, a __pycache__ directory, bin, target or obj directory).

  6. Files and directories that begin with an underscore are reserved for use by your instructor, TA, or grader.

    1. Your submitted archive file should not have any entries that begin with an underscore.
    2. Your SIM should not use or create files or directories that begin with an underscore.

  7. Written answers or graphs should always be provided in a doc subdirectory, the doc directory should be alongside your Makefile or Build.sh.

    1. Prose should be provided in either a text file, an HTML file, or a PDF file.
    2. Graphs may be embedded in your written answers (if you provide HTML or PDF). If your answers are written in a simple text file, provide your graphs in a common raster image file format (PNG, JPEG, ...), SVG, or (preferably) PDF. Refer to the graphs by name in your answer write-up.
    3. Graphs provided for assignments without a required written component should be in appropriately named files (still, of course in doc) and should be self-explanatory on viewing.5

    4. Students may always feel free to submit a README file for any assignment, but it needs to be in doc and follow these conventions.

  8. Your SIM should not prompt the user for any input, nor pause the display of console messages for the human eye.

Examples

Submission Templates

Here are example trees for submissions, one each for the most common languages used by students. If you are using another language, look at one of the templates for a similar language.

Templates with a Makefile and a Project.mak: edit Project.mak which is the intended way to configure the build.

Here is a source tarball that is a "more pure" example of a non-trivial Makefile for building C++. This example doesn't use my Project.mak build configuration file.

If you like to use IDEs such as Eclipse or M$Vs:

  1. do your work in the IDE with a simple source layout
  2. copy your code into the appropriate extracted template on a CSM Linux box
  3. test to make sure it builds and runs correctly

  4. clean it out (there is a clean target in the provided Makefiles, otherwise remove residual files by hand)

  5. tar or zip it up and submit.

If your IDE purports to generate Makefiles, then give it a try (YMMV). Be sure to test on a Mines machine!

Beware that M$ based IDEs frequently generate NMAKE files, which are a far cry from conventional Unix make compatible build files, and are uniformly mocked by gmake.

Output Formatting

Suppose a simulation assignment dictates:

  1. Your SIM should accept two arguments. The first argument is the seed for your pRNG, the second argument is the number of experimental runs.

  2. Your SIM should display 3 numerical results: the average theta, the minimum theta, and the median alpha across all the experimental runs.

Then all of the following outputs would be acceptable:

  • $ ./SIM 38478 1000
    OUTPUT 7.43  -2.1113  7483
    $
    $ ./SIM 38478 1000
    OUTPUT 7.43
    OUTPUT -2.1113
    OUTPUT 7483
    $
    $ ./SIM 38478 1000
    OUTPUT Average theta 7.43 minimum theta -2.1113  middle alpha 7483
    $
    $ ./SIM 38478 1000
    1000 experimental runs beginning!
    ... half-way there
    ... woot! look at us go
    OUTPUT Average theta 7.43 minimum theta -2.1113
    maximum theta 32.874
    OUTPUT middle alpha 7483
    whew.
    $
    $ ./SIM 38478 1000
    OUTPUT Average theta 7.43 minimum theta -2.1113 maximum theta =32.874= middle alpha 7483
    $

But this one is not acceptable for two different reasons:

  • $ ./SIM 38478 1000
    OUTPUT Median alpha=7483     Average theta=7.43     Minimum theta=-2.1113
    $
  1. The applications in this course should be pretty OS agnostic (1)

  2. The name of your directory containing Makefile or Build.sh does not have to be named top, the example is simply showing that make and bash will be run from within your top directory. (2)

  3. This means the Unix executable bit is set. (3)

  4. This does not preclude SIM existing before make or Build.sh are run, and a build script might be a mere placeholder. Such a setup is applicable for certain languages. (4)

  5. Heaven forbid, don't forget a graph title. (5)

Assignments/Requirements (last edited 2023-03-21 14:50:04 by khellman)