CENG796 Project rules, milestones and guidelines
This page contains important information regarding the 796 projects. Please read the whole page carefully, and as soon as you can. Please take note of the deadlines and re-check this guideline post regularly during the semester to remember the milestones and requirements. Mark your calendars to set your own reminders for the deadlines.
All deadlines are listed on the course homepage. All submissions will be done on ODTUClass. Please let me know if you cannot find the submission page towards a deadline.
For each submission, please read and follow the corresponding ODTUClass submission format specifications carefully.
Milestones
Milestone I: Team proposals
- Team up with a friend. Please use ODTUclass forum if needed.
- You are expected to upload your team information on ODTUclass.
- Each project group will consist of 2 students. If you cannot form a pair, I'll do random pairing. All groups will consist of pairs.
We might have one exceptional 3-member or 1-member group, depending on the active number of students taking the class.
- Please email me asap if you ever decide to practically "drop" the class.
- Please email me if you could not form a group by the deadline so that I can do that I can quickly do random pairing.
- Start working on your project proposals (next section) immediately when you form your project group.
ODTUclass submission format.
Exactly one submission (from a single member) of each project group is expected. Each group should submit one text file with the following content:
StudentID_1 Name_1
StudentID_2 Name_2
Students who end up with no groups should submit
NO_GROUP
, and email me for notification.
Milestone II: Project proposals
- Look for generative model papers published at a top venue or journal (primarily, CVPR, ECCV, ICCV, ICML, ICLR, NeurIPS, IJCV, JMLR, TPAMI) recently (ideally published within the past 18 months). Focus on papers directly relevant for this class. Exceptionally good arXiv preprints can also be considered.
- Papers proposing new unsupervised generative model formulations are particularly encouraged. The model does not have to be for the image domain, other domains are also accepted.
- Application-only papers are discouraged. However, papers addressing other directly relevant topics, such as conditional generative models (e.g., class / text conditional), image to image translation models, etc. can be considered unless they are purely application oriented. Again: papers innovating in terms of core generative model formulation are strongly preferred.
- Note that you will be expected to reproduce some of the experimental results of the paper to validate your implementation. Therefore, make sure you do not choose papers for which your compute resources are insufficient. While it is possible to reproduce results on smaller-scale datasets like CIFAR-10/100 in most cases (on free resources such as Google colab / on CPU / etc), reproducing results on high-resolution ImageNet or video datasets can be computationally very demanding. Therefore, make sure you choose papers reporting results on benchmarks feasible for your resources. (You will not be required to reproduce other large-scale experimental results of the paper.)
- A group's project paper needs to be distinct from the papers presented by group members. It is OK to work on a paper presented by a member of another group.
Policy on code and data "reuse".
- If a publicly available implementation of the paper exists, you are forbidden to make use of it. The paper should be your only resource, you should not be reusing or re-purposing existing source model implementations. Projects violating this policy may receive as low as zero-grade. Exceptionally, I may allow looking into existing code where a part of paper is obviously unclear, but you must ask for permission.
- If your implementation requires a large pretrained feature extraction model (eg. ImageNet pre-trained Inception/VGG/ResNet/etc), you may use an existing pre-trained model.
- If you need to use a data driven evaluation metric (eg. FID, Inception Score, etc), you are supposed to implement it yourself. As written in (1), you may use existing pre-trained networks typically required for implementing them.
- It is fine to download and use existing publicly-available datasets. This can be raw image/sound data or this can be a dataset of pre-extracted features (eg. VGG) if the model is to be trained and evaluated in the feature space. However, you are normally not allowed to download and use existing data that is supposed to be obtained by some part of the model that you are implementing.
- Ask me whenever you are in doubt.
ODTUclass submission format. Propose 5 paper titles in higher-to-lower preference order as a simple text file, in the following format:
- First line: HIGHEST preference.
- Last line: LOWEST preference.
- There should be 5 lines in total (one extra empty line at the very end is not a problem).
- Each line should contain the exact title of the original publication. If the same work appears also on arxiv, please use the paper title published on the conference website instead.
- Avoid quotation marks (" and ').
The submissions will be processed as follows:
- I will filter out papers that looks unsuitable.
- In case of conflicts, I will assign titles to groups by using their preference order.
- In cases of ties, I may contact the groups.
- In case none of the proposals of a group are accepted (due to higher-ranking preferences by other groups or unsuitability of the titles), new proposals will be requested.
Milestone III: Declare experimental result goals
- This will be the first milestone after the announcement of group - paper matches.
- Each group is expected to declare one qualitative (eg. image samples) and one quantitative result (eg. FID/IS/etc scores on one dataset) that will be targeted to reproduce. These results should be comparable to those reported in the paper, as a validation of your implementation. In specific cases, you may need to produce more than one result, if that is necessary to validate your implementation.
- Some papers report results only at large-scale datasets / very high resolution images. Such papers can be difficult to reproduce. This milestone exists to “force” everyone to declare their experimental result goals, ie. decide while qualitative and quantitative results that you're going to reproduce. In this way, you can both clarify your goals and realize any potential problems with your paper choice before it is too late.
- I also understand that many of the interesting recent works report high-resolution results only. If this is the case for your project, you may also consider proposing a lower resolution setting, which can greatly cut the compute resources needed. In such a case, you need to pay attention to the following in declaring your experimental goals:
- discuss the problem (ie. what experiments exist in the paper, and why reproducing all those results look problematic), and indicate whether your proposed lower-resolution setting is your main target or just a fall-back plan,
- clearly indicate your target resolution, and explain why it will still be sufficient to demonstrate the abilities of the model (you may want to visually explore sample images),
- explain how you'll compare your quantitative results with those in the paper (you may adapt/propose a heuristic to make the numbers across scales roughly comparable).
- Normally you should choose your paper carefully in the first step. But if you realize new major problems with your paper choice at this stage (eg. the paper completely lacks quantitative results, etc), please contact me immediately, explaining your problem. In the worst case, I may ask you to propose a different paper, but please note that you’ll loose time for making such a change at this late stage.
- What you declare will be your minimum goals. You may definitely optionally produce additional results, as an enhancement of your open source code.
- Important note I. Please note that failing to reproduce results is not necessarily penalized heavily, as long as the group presents and reports (as part of the project) the detailed and creative attempts and engineering efforts to fix the encountered problems. Still, there is likely to be some (minor or major) penalty in case of a large discrepancy between project results and paper results, as an incentive to try hard to reproduce the papers. Similarly, magically / mysteriously obtained good results do not necessarily result in high project grades, especially if the group fails to show the engineering process or fails to show a good grasp of the method / their own implementation at the end of the project.
- Important note II. Reproducing results at relatively small (but not exteremely small) resolutions is much better than obtaining no good results at all.
ODTUClass submission format: Upload a simple text file, declaring which minimum set of results do you plan to re-produce. In this file, give the title and URL of your project paper, and point to table(s) (you may point to specific rows) and figure(s) that you aim to reproduce.
Milestone IV: Project "Version 1" submissions
- This is supposed to be your complete and polished submission involving your own implementation of the paper you have selected in PyTorch and your experimental results.
- Submission format and additional guidelines will be announced separately. Please also check the peer-review form (see below) to better understand the expectations.
- As explained in the first lecture and the course homepage, I will grade this together with the second version at the end of the semester, as part of your project grade.
- Note that this deadline is close to the midterm date, therefore, please plan your work ahead.
- The software requirements for Version 1 (and the submission details) are given below.
Milestone V: Peer-review report submissions
- Each group will review one other project and will give written feedback, which is expected to help finding and fixing bugs in the reviewed project. Reviews themselves will be graded by me.
- This form will be used for preparing the peer-review reports: Peer review form.
ODTUClass submission format: Convert your review form into pdf, and name it as ReviewedGroup##_ByGroup##.pdf
.
Milestone VI: Project "Version 2" submissions
- This final version of the projects will be made public on a joint Github repository, where each project submission will be a sub-component of the repository. Source code authors and reviewers of each component will be clearly denoted in the repository.
- All projects are planned to be licensed with the permissive MIT License for its simplicity. Please contact me immediately (by the week 11) if you have any objections or thoughts about this, I welcome feedback and will be happy to discuss other options. If I do not receive an objection, you will be presumed to accept the license that your submission will receive.
- The software requirements for Version 2 (and the submission details) are given below.
Milestone VII: Project demos
Each group will demonstrate its project. The rules and guidelines:
- Fully complete your project before the presentation.
- Prepare your jupyter notebooks and be-ready to show your projects (possibly using screen sharing).
- Each presentation should be around 8 (max 10 mins) minutes-long in total. Rehearse accordingly.
- Explain the key ideas and key equations of the paper that you've implemented, using the summary that you have written into the jupyter notebook.
- Explain your experimental result goals.
- Show your own results (qualitatively and quantitatively) and explain whether you have reached your experimental result goals. If not, summarize your efforts and your ideas on what's going on (please try to be more precise than just "wrong hyper-parameters").
- Quickly go over your code (show jupyter notebook and other python files), briefly summarize your implementation.
- Tell us about the difficulties that you have encountered in your project (make sure these are also summarized in the jupyter notebook).
Software requirements for Version 1
- Each project should accompany a Jupyter Notebook file that contains sections for:
- Paper information, your information (the code authors).
- Hyper-parameters of your model.
- Training and saving a model.
- Loading a pre-trained model and computing qualitative samples/outputs from that model.
- Reproducing the result(s) in the form of plots and/or tables, as you've declared that you have declared. Please add a brief explanation / pointer to the paper so that a reader can understand what these results are.
- A section describing the challenges (if any) that you have encountered when implementing the paper. This should primarily include implementation details that you could not find in the paper, the assumptions made that you had to make (eg. number of layers).
- The name of your jupyter notebook should be
main.ipynb
.
- The Jupyter notebook should come with pre-computed outputs. This is to show your results without having to re-run your notebook.
- You should work on Python3 and make your code compatible with the current version of Anaconda Individual Edition.
- A bash script called download_data.sh that downloads any necessary data (datasets, pre-trained models, etc.) that you could not include in your ODTUclass submission due to file size.
- License.txt containing MIT License.
- Your submission should also include a file named
goals.txt
. This file should contain a copy of your previous project experimental result goals submission. At the end of this text file, add the separator line —— version 1 submission ——
and then include a (brief) description explaining:
- whether you had to make any changes in your goals or not (eg, target dataset might have changed),
- how much you have been able to reproduce the results that you have aimed to reproduce,
- if you could not reproduce the results that you have targeted: what is your future work plan (discuss what is missing in your implementation / what might be buggy / etc.)
In this file, you may also refer to your jupyter notebook section on the difficulties encountered. No need to re-write here what you’ve already explained in that section.
ODTUClass submission format:
- Put all your submission content into a folder with a proper model acronym (use the one suggested by the paper, e.g. SNGAN, or choose one of your own choice if needed), before zipping.
- Zip your folder (including the pre-trained model) and upload to ODTUclass. If your zip takes more than 80mb, please put (some of) your data / model files to an external location and include
download_data.sh
to download them (as previously explained in the requirements). Rename the zip file as group##_version1.zip
.
You will receive peer feedback for your v1 submissions. It is suggested to start working towards meeting the v2 requirements and fixing any problems in your v1 submissions, without waiting for reviews to start fixing the problems that you already know.
It is perfectly OK to satisfy (some of) v2 requirements within your v1 submissions.
Software requirements for Version 2
Below are requirements for the version-2 final version of the projects. While I encourage you to do your best in meeting version-2 requirements directly with version-1, you are not required to satisfy version-2-only ones in your version-1 submissions. Enrich your Jupyter notebook with the following in Version-2:
- Jupyter notebook (
main.ipynb
) updates:
- A detailed and accessible summary of the paper that you have implemented. Include mathematical details with equations (you can write latex directly within jupyter files via markdown). Preferably add this to the top of the jupyter notebook.
- A section listing and briefly explaining the main step of your implementation, ie. the workflow of the code. Also make sure that your python codes are well-documented. Note that your Jupyter notebook is not supposed to contain the full implementation, it should import only main models and their functionalities.
- Device (GPU/CPU) support. Make sure all your code can be made run on a particular GPU or CPU by changing on constant on the top of your Jupyter notebook, e.g. by using to(device) properly everywhere. Also make sure that pre-trained model is loaded to the right device, eg. by feeding map_location to torch.load().
- Any installation guidelines (other than Anaconda and PyTorch).
- Reminder: make sure your jupyter notebook still contains pre-computed outputs, which is super-important for people browsing your code online on GitHub.
- All version-1 requirements must be met also in version-2.
- Extend your
goals.txt
by adding the separator line —— version 2 submission ——
and then including a (brief) description about the following:
- whether you had to make any changes in your goals or not (eg, target dataset might have changed),
- how much you have been able to reproduce the results that you have aimed to reproduce,
- if you could not reproduce the results that you have targeted: discuss what is missing in your implementation / what might be buggy / etc.
- Create a
README.md
file, and fill it in according to the following template:
# [PAPER TITLE](https://.../link-to-the-paper.pdf)
Paper author 1, author 2 and author 3
*CVPR 2030*
**HERE: Add a simple picture from your results**
This folder provides a re-implementation of this paper in PyTorch, developed as part of the course METU CENG 796 - Deep Generative Models. The re-implementation is provided by:
* Group Member 1, member1@metu.edu.tr
* Group Member 2, member2@metu.edu.tr
Please see the jupyter notebook file [main.ipynb](main.ipynb) for a summary of paper, the implementation notes and our experimental results.
**Optional**: installation instructions, and any other comments you may want to add.
- Create a
info.yaml
file, and fill it using the following format:
- acronym: Project acronym
title: Paper title
year: The year the paper was published
venue: The name of the conference / journal where the paper was publish (if not published yet: arXiv)
paper_authors: Paper authors, comma-separated list (e.g. Johann Sebastian Bach, Ludwig van Beethoven, Johannes Brahms)
group_members: Project group members, comma-separated list
- You are also expected to address the problems raised in the reviews. (You are not required to follow suggestions that are outside the scope of the announced project requirements.)
ODTUClass submission format:
- Put all your submission content into the acronym-named folder, before zipping.
- Please zip your folder (including the pre-trained model) and upload to ODTUclass. If your zip takes more than 80mb, please put (some of) your data / model files to an external location and include
download_data.sh
to download them (as previously explained in the requirements). Rename the zip file as group##_version2.zip
.
Although not very likely, a few more requirements can be added later. You may also want to look at the previous years' projects, especially the better looking ones. Don't rely on a sample project for meeting the requirements, though. A project example is not a substitute for the requirements, and there are more than one way to satisfy most of these requirements.
Finally, note that the final project demos will be based on sharing your screen and explaining your Jupyter notebook. You will not prepare additional slides. The quality of your Jupyter notebook will also affect your demo quality.