INF203 project finalization and submission

This worksheet leads you to the completion of the INF203 programming project. It is a continuation of the preceding worksheets:

1. Worksheet 1: Pair potential (deadline 5.6.2025)
2. Worksheet 2: Monte Carlo simulation (deadline 11.6.2025)
3. Worksheet 3: Test area method (deadline 16.6.2025)

Submit the final complete project material through Canvas by Saturday, 21st June 2025, 17.30 CEST. This includes:

• Your complete code base, as a Python package.
• The project report in PDF format, as specified below under no. 4.5. The project report must be written using LaTeX, but do not submit the LaTeX sources, only the PDF.
• The requirements register as a spreadsheet in ODS or XLSX format, including columns stating whether the functionality was actually implemented (y/n), and whether it was validated or tested (y/n).
• Any simulation output or data that you would want to share as long as they are not very large. Do not include any XYZ trajectory files (i.e., XYZ files with multiple frames) unless they are smaller than 4 MB in total. Do not include any other very large files.

The above should be uploaded on Canvas in the form of a single zip (or tar.bz2 or tar.gz) archive.

4.1 Input from JSON file and command line

Create a class Orchestrator, in ./src/ljts/orchestrator.py, for running and controlling the simulation.

The parameters for orchestrating the simulation should be read from a JSON file (example: vle-0.80-reference.json). The filename should be passed to the main Python script ./main.py as a command line argument.

4.2 Uncertainty analysis

Implement uncertainty analysis using time-series block averaging in one or multiple code files in the directory ./src/timeseries/. Do it such that you can reuse your code for other purposes, including use cases unrelated to molecular simulation. Apply the uncertainty analysis methodology to obtain and explicitly output margins of error for the sampled potential energy ⟨E_pot⟩ and the quantity ⟨exp(-ΔU / T)⟩, and use the result for the latter to obtain a value and uncertainty for the surface tension γ computed from the simulation.

4.3 Testing and validating your code base

Test and validate your code's functionalities in order to establish whether they work. Use both unit tests and holistic validation (e.g., integration tests and acceptance tests) for at least some of the functionalities. Update your requirements register to state for each functional requirement whether it was implemented (y/n), whether it was tested or validated (y/n), and what group member had the lead responsibility for the feature.

4.4 Simulation production run(s)

With the above established, use your code to obtain some interesting results - best of luck!

4.5 Package your code and compile the project report

Prepare the final version of your code for submission in the form of a Python package.

Suggested document structure for the project report:

1. Introduction
   1. Group composition and responsibilities
   2. Shared repository and tools for collaboration
   3. Agile methodology and requirements analysis
   4. User guide
2. Implementation
   1. Code and class structure
   2. Commenting
   3. Advanced OOP techniques
   4. Python package
3. Functionality and validation
   1. Testing and validation strategy
   2. Initial configuration setup and input/output
   3. Pair potential and Monte Carlo method
   4. Test area method and surface tension calculation
4. Sampling and data analysis
   1. System equilibration and production
   2. Uncertainty analysis
   3. Data processing for console output
   4. Data processing for diagrams and visualization
5. Simulation results
   1. Vapour-only reference system
   2. Vapour-liquid reference system
   3. Any other results
   4. Comparison to results from the literature

Some style advice:

1. The purpose of the report is to help the examiners grade your submission.
2. The document must be written in LaTeX - any style will be good. Any length in number of pages is allowed. The submitted PDF must be less than 4 MB in size, and the complete ZIP file should not be so large that it causes any problems for Canvas.
3. Be concise.
4. The examiners will read the code and the requirements register, so there is no need to repeat any of this in its entirety in the report. But the report can help the examiners figure out where to look for what purpose. So it helps to include pointers to a method and source filename, or to a labelled element of the requirements register when you are referring to it.
5. Do not include any code fragments longer than seven lines of code. It is preferrable to explain yourselves using pseudocode or diagrams if you want to explain any parts of code that are more complex.
6. This is not an academic text, and it does not matter if the English is not perfect. Please don't run it through an LLM for language polishing. (This is technically allowed, however.)
7. You do need to cite academic references if you use them, for example when comparing to literature data, or when implementing any special methods that we did not discuss in the lecture. References are not needed for the methods that we did discuss in the lecture, such as E-R diagrams, the LJTS model, the Metropolis algorithm, the test area method, or time-series block averaging.
8. Visualize your simulation results using diagrams. These should follow the usual common-sense principles for good use of diagrams. Axes should be clearly labelled, captions should state what exactly it is that the diagram shows. Always ask yourselves: What information do we want to convey with this diagram? Is this a good way to convey that information?
9. Do not include any screenshots.
10. The external examiner does not speak Norwegian, and in case of an appeal, the appeals examiner might not speak Norwegian either. So all the requirements, comments in the code, and speaking names of entities (files, classes, methods, variables, etc.) should be in English, or they will not be understood property. This of course applies to the report as well.

Index