UCT EE Wiki - User contributions [en-gb]

Message Passing Interface (MPI)

2025-03-17T20:00:57Z

Swinberg: Added info about compiling and running a standard MPI program

[[Category:Frameworks]]
[[Category:Software]]

= Overview =
Message Passing Interface (MPI) is a standardized and portable message-passing standard designed by a group of researchers from academia and industry to function on a wide variety of parallel computing architectures.

= Installation =
== Debian based Operating Systems ==
This has been tested on Raspbian.

<code>$ sudo apt-get install openmpi-common openmpi-bin libopenmpi-dev </code>

= Compiling and Running =

To compile (from command line / Bash), on most installations, you generally would use:

mpicc -o exename myfile.c # this would combile file myfile and the generated executable would be called exename

To start multiple instances of the program (as in the default number of nodes, which would be the number of cores your computer has) and to start running the program you would do:

mpirun ./exename # this is to execute the generated exename executable in the current directory

To start a particular number of instances, in this case 4 nodes, and to start running them you would use:

mpirun -n 4 ./exename # start exename with 4 nodes

= Tutorial =
See [https://computing.llnl.gov/tutorials/mpi/ this link] for usage notes.

STM32CubeIDE

2024-09-13T06:58:57Z

Swinberg:

[[Category:Software]]
[[Category:IDEs]]

STM32CubeIDE is an all-in-one development tool, part of the STM32Cube software ecosystem which is supported on multiple platforms (Linux, Windows, and Mac). STM32CubeIDE is an advanced C/C++ development platform with peripheral configuration, code generation, code compilation, and debug features for STM32 microcontrollers and microprocessors. It is based on the Eclipse®/CDT™ framework and GCC toolchain for the development, and debugging using GDB. It can be integrated with hundreds of existing plugins that complete the features of the Eclipse® IDE.

STM32CubeIDE going beyond just C/C++program development; in incorporates facilities for build and stack analyzers that provide useful information to investigate project status, memory requirements, program space and data space use among other analysis reports.

== Installing ==

The latest version of STM32CubeIDE, as well as links to other tools in the STM32 collection of development tools, is available at: https://www.st.com/en/development-tools/stm32cubeide.html

'''Note:''' You need to create an account (this is available for free) and sign in to download tools.

STM32CubeIDE

2024-09-13T06:51:07Z

Swinberg: Added page

Online Content Creation

2023-09-25T12:32:30Z

Swinberg: Added suggestion for using Handbreak to reduce video file size

[[Category:Content Creation]]
= Overview =
This page contains some suggestions for creating better quality online learning content. These are mostly opinion based, but the idea is to use this page as a single point of access for ideas, tips and tricks when creating online content.

For more information, visit [[:Category: Content Creation]].

= General =
* Use a script. This helps prevents "Uhms and ahs" and ensure you convey the information you want to as coherently and briefly as possible.

= Videos =
* You can use OBS to record your screen: https://obsproject.com/
* You can use Kdenlive to do any editing: https://kdenlive.org/en/download/
* Recommend using Handbrake https://handbrake.fr/downloads.php for reducing the size of videos and adjusting the resolution (recommend using the default present "Fast 1080p30" which is suited to full HD resolution (1920 x 1080 pixels) that works well on PCs (you may want to reduce if targeting smartphones and not having particularly complex imagery in your presentations).

= Audio =
* For recording, any software will work
* When recording, normalizing and removing background noise makes the audio much more professional and easier to listen to.
** Record a second or so of silence to allow you to capture the noise floor
** You can use Audacity to capture the noise floor and remove it.
** You can use Audacity to normalize the volume. -1dB is the standard normalization volume

= Workflow =
== YouTube Tutorial Videos ==
For YouTube videos, a suggested approach is as follows:
# Write a short script, making notes of what you would like to say.
# If you are doing a demonstration, run through the demonstration and ensure you touch on all points, taking note of where you may need to pause, or edit out things that take time, such as a loading bar
# Record the script in Audacity, being sure to normalize and remove noise floor.
# While playing back the audio to yourself, use OBS Studio to record the actions taken.
# Edit the recorded audio and video together using Kdenlive

== Slideshow Videos/Lectures ==
You can:
# Insert voice recordings into the slides.
## This can be arduous for students who want to play/pause recordings, or go at a different pace.
## In PowerPoint, you can export slideshows as videos. This option may save time if you're looking at creating simple videos.
# Use OBS to record both yourself and the slideshow.
## This makes a simple video, though may limit students who don't have much data to watch videos.
## You can use Kdenlive or other software to split the audio and video, and upload the audio separately to Vula, so students can download the audio to listen to while they go through the slides
# Use the process described in "YouTube Tutorial Videos" above
## This allows you to insert other videos, clips, etc with ease

Category:Lab Equipment

2023-06-21T20:39:20Z

Swinberg:

This page lists info about commonly used items of larger lab equipment, which are often essential for the development and testing of projects done in the department. As in things beyond the small basic items e.g. multimeters, power supplies, and function generators.

Category:Lab Equipment

2023-06-21T20:31:13Z

Swinberg: Adedd description of lab equipment category

This page lists info about commonly used items of lab equipment, which are often essential for the development and testing of projects done in the department.

Perspex Cutter

2023-06-21T20:29:10Z

Swinberg: Added page

[[Category: Lab Equipment]]
= Overview =

Perspex cutter is available in the lab. Dimensions: 740x460mm.

Some stock of perspex sheets is usually available, but do ask lab administrator in advance for availability and for details and type to use should you be doing more than one or two small items (wanting to use s sheet that isn't transparent).

Embedded Systems

2023-06-21T20:20:07Z

Swinberg: Updated embedded platforms used in courses

[[Category:Hardware]]
= Overview =

= Systems with Departmental Support =
These boards are systems that are used at UCT within certain courses. These platforms are more likely to have comprehensive resources available on this wiki.

{| class="wikitable sortable"
|-
! Course !! Category !! Board
|-
| Embedded Systems I || Microcontroller || STM32F0
|-
| Embedded Systems II|| SBC || STM32F0 (2019-2021: Raspberry Pi)
|-
| High Performance Embedded Systems|| FPGA || Digilent Nexys A7
|-
| High Performance Embedded Systems|| FPGA || Digilent Nexys 4 DDR
|}

= Other Systems Available in the Department =
These are systems that are used in the department but do not form part of a specified curriculum. These include:

{| class="wikitable sortable"
|-
! Category !! Board
|-
| Microcontroller || Discovery STM32F4
|-
| FPGA || NI LabVIEW FPGA
|-

|}

= Resources Available =
Resources are available on the following:
# [[RaspberryPi]]
# [[Xilinx]]

Templates for Articles, Dissertations and Reports

2023-03-16T19:59:15Z

Swinberg:

[[Category:Research]]

This page provides useful links to Templates for Articles, Dissertations and Reports (which we're calling the ''TADR'' repository). This is aimed to be a collection of useful contributes that may be useful to students in the UCT Electrical Engineering department and are used for some course project reports (these may be suitable for use in other areas, see licensing policies related to the contributions, all emphasise the 'use at own risk' policy and are generally provided under an OpenCommons license allowing adaption and redistribution as needed without the need to request permission from the original authors). '''Note:''' in the case of a thesis or dissertation please ensure that you view the guidelines and templates provided by your department and/or faculty and adhere to those guidelines (we do not guarantee the conformance of our templates to those that you may be required to use for your particular work).

* '''LaTeX_UCT_Report:''' https://github.com/jpt13653903/LaTeX_UCT_Report
** This contribution provides Latext templates usable for either: PhD theses, MSc dissertations, BSc final year project reports, academic articles or project reports.
** The README.md in the GitHub site for this project provides information about how to select which style of output you want (i.e. report/dissertation/article) together with the Creative Commons License permitting use and adaptation of these templates.
** This project was planned around allowing authors to have a consistent approach and file structure for all their reports and articles. We welcome any suggestions you may have or difficulties you might experience and have suggestions for how to improve the usability. We hope these resources will help boost your productivity and perhaps encourage wider use of Latex.

* Microsoft '''Word Templates'''
** The below provides a UCT dissertation Word template relevant to engineering:
** MSc/MEng dissertation template: [[Media:MSc YourLastName ver.docx.zip]]
** Note regards suggested file naming convention: ''MSc'' indicates degree. Replacing ''YourLastName'' with your last name will help your supervisor keep track of files downloaded. The ''ver'' is useful to indicate the version number of the file (e.g. the number increases with later revisions) or a date of the file (to help you and your supervisor know they are using the latest version).

Templates for Articles, Dissertations and Reports

2023-03-16T19:55:20Z

Swinberg:

Templates for Articles, Dissertations and Reports

2023-03-16T19:55:02Z

Swinberg:

Templates for Articles, Dissertations and Reports

2023-03-16T19:49:55Z

Swinberg:

File:MSc YourLastName ver.docx.zip

2023-03-16T19:47:04Z

Swinberg: This is a zipped MSc / MEng .docx format UCT dissertation template.

== Summary ==
This is a zipped MSc / MEng .docx format UCT dissertation template.

2022-03-11T08:31:40Z

Swinberg: /* Export display from Linux to Windows */

[[Category:Software]]
= Overview =

The X Window System, or X11, is a windowing system used for Linux and Unix operating systems. X provides the basic infrastructure for a GUI environment. A useful aspect of this is that you can export the display from your Linux shell login to a different display on the PC you are using or to a desktop on a remote computer. Or even a virtual desktop that you can set up using VNC or TightVNC - this VNC desktop you can then view on the same or different computer from either Windows or Linux.

The X.Org Foundation leads the X project and hosts reference implementation for it. X is available as free and open-source software under the MIT License. For more information on the X standard see the [https://x.org/wiki/ X.Org Foundation] https://x.org/wiki/, and https://en.wikipedia.org/wiki/X_Window_System.

= Exporting X display =

You can export your Linux X display using the DISPLAY environment variable in Linux. This can be done either to another Linux machine or to a Windows machine where you are running a X server. The tips below indicate the procedure of how to export the display.

== Export display from Linux to Linux ==

Assuming you have your Linux desktop open, and you want to log into another machine, let's call it ''remotepc'', via ssh.

How to export display automatically via ssh -X option:

Open a terminal window. Type in the following:

xhost + # this will allow other systems to display to your machine
ssh -X remotepc # this will login in to remotepc and export the display to where you logged in from

This is all you should need to export the display to the desktop you logged in from. Test it out by starting another terminal, e.g. run: xterm & and see that the terminal pops up on your desktop.

If the -X option did not work, then from your local machine do as follows:

ifconfig # find what IP address your machine is using
# e.g. consider that your machine has IP 192.168.0.1
xhost + # allow other machines to connect to your display
ssh remotepc # this login in to remotepc but doesn't attempt to automatically export display
export DISPLAY=192.168.0.1:0 # explicitly export display to your local machine, to desktop 0

You should now be able to start programs on the remote machine and have any GUI for the program open up on your local machine. You could test it using xtern & and see if a new terminal window pops up.

== Export display from Linux to Windows ==

In order to export the display from Linux to Windows, you need to have an XWindows server installed on your local machine. An excellent and free option is use of the [https://sourceforge.net/projects/xming/ XMing] server available for Windows, see https://sourceforge.net/projects/xming/.

Alternatively, you can set up a [https://www.realvnc.com/en/connect/download/vnc/ VNC server] on the Linux machine you are logging in to, to create a virtual desktop. Then export the display to the VNC virtual display, and use a [https://www.realvnc.com/en/connect/download/viewer/ VNC viewer on Windows (or Linux)] to view and interact with the virtual display.

On Ubuntu Linux, you can simply install a vncserver using apt-get, TightVNC server is suggested as it can save bandwidth, can install using: sudo apt install tightvncserver.

The following indicates how to setup and access a Linux GUI displays using XMing viewer on Windows:

1. First install XMing on your Windows machine (see: https://sourceforge.net/projects/xming/)
2. Once installed (and started, which happens after install by default) you will get a XMing logo appear in your taskbar:

[[File:Https://imgur.com/a/HshaB7L|thumb|Xming]]

Xwindows

2022-03-11T08:20:07Z

Swinberg: /* Export display from Linux to Windows */

[[Category:Software]]
= Overview =

The X Window System, or X11, is a windowing system used for Linux and Unix operating systems. X provides the basic infrastructure for a GUI environment. A useful aspect of this is that you can export the display from your Linux shell login to a different display on the PC you are using or to a desktop on a remote computer. Or even a virtual desktop that you can set up using VNC or TightVNC - this VNC desktop you can then view on the same or different computer from either Windows or Linux.

The X.Org Foundation leads the X project and hosts reference implementation for it. X is available as free and open-source software under the MIT License. For more information on the X standard see the [https://x.org/wiki/ X.Org Foundation] https://x.org/wiki/, and https://en.wikipedia.org/wiki/X_Window_System.

= Exporting X display =

You can export your Linux X display using the DISPLAY environment variable in Linux. This can be done either to another Linux machine or to a Windows machine where you are running a X server. The tips below indicate the procedure of how to export the display.

== Export display from Linux to Linux ==

Assuming you have your Linux desktop open, and you want to log into another machine, let's call it ''remotepc'', via ssh.

How to export display automatically via ssh -X option:

Open a terminal window. Type in the following:

xhost + # this will allow other systems to display to your machine
ssh -X remotepc # this will login in to remotepc and export the display to where you logged in from

This is all you should need to export the display to the desktop you logged in from. Test it out by starting another terminal, e.g. run: xterm & and see that the terminal pops up on your desktop.

If the -X option did not work, then from your local machine do as follows:

ifconfig # find what IP address your machine is using
# e.g. consider that your machine has IP 192.168.0.1
xhost + # allow other machines to connect to your display
ssh remotepc # this login in to remotepc but doesn't attempt to automatically export display
export DISPLAY=192.168.0.1:0 # explicitly export display to your local machine, to desktop 0

You should now be able to start programs on the remote machine and have any GUI for the program open up on your local machine. You could test it using xtern & and see if a new terminal window pops up.

== Export display from Linux to Windows ==

In order to export the display from Linux to Windows, you need to have an XWindows server installed on your local machine. An excellent and free option is use of the [https://sourceforge.net/projects/xming/ XMing] server available for Windows, see https://sourceforge.net/projects/xming/.

Alternatively, you can set up a [https://www.realvnc.com/en/connect/download/vnc/ VNC server] on the Linux machine you are logging in to, to create a virtual desktop. Then export the display to the VNC virtual display, and use a [https://www.realvnc.com/en/connect/download/viewer/ VNC viewer on Windows (or Linux)] to view and interact with the virtual display.

On Ubuntu Linux, you can simply install a vncserver using apt-get, TightVNC server is suggested as it can save bandwidth, can install using: sudo apt install tightvncserver.

The following indicates how to setup a VNC viewer on Windows:

Xwindows

2022-03-11T08:06:34Z

Swinberg: /* Export display from Linux to Linux */

Xwindows

2022-03-11T07:59:23Z

Swinberg: adjusted text on export DISPLAY

Xwindows

2022-03-11T07:58:13Z

Swinberg: Description of exporting display

Postgraduate Research

2021-08-21T14:32:23Z

Swinberg: Added to referencing info

[[Category:Research]]

= Overview =
A special thanks to Dr Yunus Abdul Gaffar, The initial author of this initial guide.

For more resources pertaining to research in the EE Department at UCT, see [[:Category:Research]].

= What is research =
Research is a logical and systematic search for new and useful information on a particular topic. It is an investigation of finding solutions to problems through objective and systematic analysis.

= What is design =
Design is the process used to create something to solve a problem. Design involves the transformation of an initial user requirement to produce documentation instructions on how to realise the end product. In determining a solution, barriers must be overcome. A design assignment, there, is an engineering problem and involves sub-problems that must be addressed.

The design process typically consists of the following steps:
# User requirements: client describes the problem and constraints (time, budget, using specific components) that the solution must fit within. Engage with client to understand who is going to use the product, where is it going to be used and how often, and for how long (lifespan) is it going to be used. Separate the core requirements from the ‘nice to have’ ones
# Technical requirements: translate the user requirements into concise technical requirements that contain technical jargon.
# Identify multiple solutions: synthesises a range of potential solutions to the problem or a range of approaches to developing a solution that is consistent with assumptions, premises, limitations and constraints
# Evaluates the potential approaches against criteria. Examples of criteria include cost, efficiency, performance, reliability
# Chooses a preferred approach and presents reasonable arguments to justify this decision
# Develops the full design of the selected option. This can include developing a functional-flow block diagram for the proposed solution, and a block diagram showing the major sub-systems + interfaces between sub-systems: for each subsystem, identify multiple solutions and justify your choice based on the requirements and constraints of the system
# Test each sub-system to ensure that it is functioning accurately as expected
# Perform integration and testing: Build prototype and perform testing. Assess if system technical requirement are met
# Develop improved prototype by iterating through steps 6 -> 7 -> 8 . The more iterations are done, the better the quality of the developed system.
# Produces design documentation for implementation. A design document provides detailed information or the ‘blueprint’ to implement the proposed solution.

= Postgraduate studies =
Note: keeping a research journal throughout your postgraduate studies can be useful to document ideas, problems, notes and reminders. During measurement trials, this is especially useful and will help a lot in the write up phase. A journal can be a hardcover book, or a word document, a blog or a combination of these.

== Masters Degree ==
A Masters degree is training to equip candidates with skills necessary for further independent research. The dissertation should demonstrate that a candidate has the ability to be adequately acquainted with the relevant literature, has mastered appropriate techniques and analytic methods, assess the significance of findings in a thorough and logically-coherent manner, shows evidence of critical and independent thought and the write-up of the dissertation is satisfactory in presentation and literature style. The dissertation does not need to involve original research or distinctly advance knowledge of the subject.

== PhD Degree ==
A PhD degree shows that a candidate can work independently and make an original, significant and meaningful contribution that adds to the existing body of knowledge. Student must demonstrate that he/she is working at the cutting edge and at the academic forefront in the topic. Evidence of a ‘significant contribution’ includes publishing in accredited journals and writing a good quality, polished PhD thesis. The ideas relating to the original contribution of the PhD work should come directly from the PhD candidate and not from the supervisor. This shows that the PhD candidate can think creatively, which is one of the skills that it certified when a PhD degree is granted. Examples of an original contribution can include:
* Providing a new angle on a previously researched problem
* Providing a single new observation
* Bringing new evidence to an old issue or taking a particular technique and applying it to a new area
* Carrying out empirical work that has not been done before or making synthesis that has not been made before
* [https://writepass.com/journal/2013/05/how-to-demonstrate-significant-contribution-original-study-in-your-phd-thesis/ How to demonstrate Significant Contribution & Original Study in your PhD Thesis]

Critical and creative thinking are two important outcomes of a PhD degree. Research what these are and how to further develop
your critical and creative thinking skills.

A PhD degree is typically examined in the context of the scientific process, which is made up of the following steps
# Research questions are stated
# Background research is done
# A clear, concise and achievable hypothesis is carefully phrased
# The hypothesis is tested by doing an experiment
# The data obtained from experiments is analysed and conclusions are drawn

= Choosing a field of study and a research topic =

There is a difference between a field of study and a broad research topic. Examples of a field are “passive radar”, ‘radar imaging’, ‘cognitive radar’. Examples of a research topic is “Optimum placement of receivers for FM-based passive radar for detection and tracking of aircraft” or “Radar imaging of small boats in high sea states”.

A field of study is more general and does not focus on a problem. A research topic is more focused and does focus on a problem. When looking for a field to work in, look at ‘hot-topics’, ie topics that there are recent publications in journals and conferences and researchers are actively trying to advance the field by contributing knowledge

When choosing a broad research topic, ensure:
* You are interested in the topic and developing/applying the skills required to complete the research. You are going to spend many months on this single topic and being passionate about is a key ingredient.
* Topic is not ‘saturated’, ie not have so many publications that there is little room left to make an original contribution.
* Enough literature that a critical literature survey can be written to show understanding of the published literature and the recent findings
* You have the time/budget/skills to develop a radar to get measured data or have access to equipment/radar to get measured data to sufficiently address your research objectives. Or, use existing good quality measured datasets. For new fields of study, measured data might not be critical. Theory and simulations may be enough.
* A simulator can be developed to obtained simulated data to compare against measured data and to generate simulated data for scenarios that is difficult/time-consuming to measure
* ‘Nice to have’: recent books on the field/topic, IEEE journal or magazine review on the field/topic, accept to experts (supervisor, industry partner, international expert), dissertations/thesis on the topic, existing datasets for initial analysis to get an understanding/appreciation for the complexity of the problem

The next step is to fine-tune the broad research topic to a more focus topic, then to phrase research objectives or research questions.

It is challenging to refine a broad research topic or to identify a ‘good research problem’. There are many problems out there: some are solvable and others are not, some are important and some are not. A ‘good research problem’ is one that is both solvable and important. The process of finding a ‘good research problem’ involves:
* reading the literature to understand what has been done and the boundaries of existing knowledge. However, if you spent too much time reading the literature and believing everything, you’ll never notice the flaws. While experts that publish are knowledgeable in their area, they rarely admit what they don’t know. Furthermore, experts have biases and work within hidden constraints. If you don’t read the literature enough, you may have doubts of what can be achieved. Reading the literature requires a balance. Hamming suggests reading the literature until the problem becomes reasonably clear. Then stop reading the literature and think through the problem yourself and brainstorm solutions. Think about how you would slightly change the problem to be the ‘solvable’. In conclusion, reading to find solutions does not lead to great research.

PhD students: the PhD candidate leads the process to identifying and refining the topic. This is because the journey of "finding the problem" and "clarifying the problem" is part of the PhD work. It is a skill that every PhD candidate needs to learn. If your supervisor gives you a clear topic + hypothesis + research objectives, and clearly outlines your methodology, what data should be used and what outcomes to expect, then this is more master’s research than independent PhD research.

= Roles of the students and the supervisor =
== Responsibility of the students ==
The following is taken from the UCT EBE postgraduate handbook:
* To accept that the primary responsibility for his/her education rests with the student. This includes selecting a topic for research, setting up meetings and developing and managing a plan to complete your postgraduate studies.
* To demonstrate a reasonable work ethic and to make every effort to meet the normal throughput rate (2 years for a Masters student, 4 years for a PhD student)
* To share ideas and to work collegially
* To participate in and to contribute to the life of the department
* To assist in the mentoring and orientation of fellow students from outside Cape Town
* To commit to co-publication with the supervisor
* To commit to constructive feedback at the end of the process

== Responsibility of the supervisor ==
The following is taken from the UCT EBE postgraduate handbook:
* To provide quality supervision on a regular basis (as a guideline, a minimum of one hour per week)
* To respond timeously to the submission of written work requiring feedback.
* To arrange for a suitable replacement if the supervisor is absent for a lengthy period (more than 3 weeks)
* To treat the student with unfailing respect and politeness
* Providing an opportunity for the student to teach undergraduate students in the candidate's area of growing expertise
* To organise a seminar by the student, involving staff and senior students in the Department
* To facilitate postgraduate students, on a voluntary basis, playing a mentoring role to undergraduate students
* To assist in the incorporation of the student into the social life of the department

== UCT Memorandum of Understanding ==
The MoU is an agreement between supervisor and student that serves the following purposes:
* Clarifies responsibilities between supervisor and candidate
* Contains a plan of work for the next 12 months or up to completion. Important milestones should be clarified
* For returning students, it contains a comparison of last year’s plan with the actual progress achieved

= Writing a research proposal =
The contents of a proposal, as given by the UCT Researchers guide, are as follows:
* Title: should give a clear indication of what the study is about
* Brief description of the area of research: locate the proposed research in its wider context
* The research questions: Crisply stated single question that can later be broken down into multiple sub-questions
* Rationale: gives a motivation of why you chose this area of research and what contribution the completed research work will make to our understanding of the field.
* Literature review: Sufficient insight of the literature to justify the research questions. Locates the proposed research in the context of existing work. Literature survey must have a direct link to the problem/questions/objectives being addressed in the thesis.
* Research methods: These indicate what techniques/methods to be used to address the research objectives.
* Research design: Addresses how the project will be broken down and what key decisions need to be made
* Data collection and analysis: what data will be collected (simulated? Measured?). How will data be collected? How data will be analysed to fully address the research objectives stated in the work
* Research ethics: If the project involves working with humans or animals, ethics approval needs to be obtained before the search begins.
* Thesis outline: prove a preliminary outline of the dissertation/thesis, indicating chapter and heading titles
* Timeline: short research plan identifying milestones and how the research work and write-up will be completed in the specified time
* List of references: reference all literature used in the proposal

== For Masters students ==
The following are taken from UCT EBE postgrad handbook:
* Clearly explain the research topic that will be investigated. Include a background section that describes the application and why this work is meaningful, ie has a real-life application and state all research objectives
* Include a literature survey that shows familiarity with the central literature within the broad field of study
* Provide clarity on the research methods or the methodology used to achieve the research objectives stated
* Typical length of masters proposal is less than 10 pages and submitted 3 months after registration for research project

== PhD Seminar ==
A PhD Seminar should demonstrate the following (from UCT EBE postgrad handbook):
* The candidate is familiar with the main literature in the field
* There is sufficient scope in the topic for a PhD and there is clarity in the stated hypothesis and research questions/objectives
* The candidate has the right background, undergraduate degree and ability to undertake the work
* The potential contribution to knowledge has been identified and there is a clear definition of the key questions to be addressed in the context of the proposed hypothesis
* The method of research is sound and achievable and there is a clear knowledge of the experimental procedures to be used and the methodology to be pursued in analysing the results

== PhD proposal ==
A PhD proposal intends to (taken from UCT Researchers guide):
* Indicate the focus for research
* Set out aims of the research project
* Indicate how the student intends to achieve those aims
* Provide a benchmark which progress is measured and adjustments made
* Typical length of PhD proposal is between 15 – 20 pages and can take 6 weeks to 6 months to complete

= Broad Chapters of a Research proposal =

== Problem statement or research objectives ==
A research problem is a statement about an area of concern, a condition to be improved, a difficulty to be eliminated, or a troubling question that exists in scholarly literature, in theory, or in practice that points to the need for meaningful understanding and deliberate investigation.

It should contain:
# Clear problem formulation
# Clear, achievable, concise, clearly scoped + application clear. Also mention what is not in the scope of the project.
# Each research objective should have a direct link with results presented later in the report
# Original, engaging and thought provoking

For a PhD:
* The hypothesis should be a golden thread uniting each chapter in a common story
* The hypothesis should be clear, concise and results in the thesis should confirm if the hypothesis is true or false

Note: reference work/code used that was generated by other people

== Theory related to your research objectives ==

* Identify relevant theory concepts that need to be understood and written up
* Write up theory using diagrams/photos/graphs, and simple examples to explain key concepts
* If the theory is not too long, then can include this into Chapter 2 before the literature survey write up
* If theory is long, then put this as a separate chapter before the chapter on literature survey

== Critical literature survey ==
* Use academic search engines (IEEE Explore, Scopus, Engineering Village, Google scholar) and effective search phrases to find credible literature (journals, conference papers, not websites/blogs) in the field.
* Search for literature in the general field and slightly outside of your topic. Your literature survey will start off looking at the broad field and then tunneling down to your specific research objectives.
* Credible literature in decreasing order are: textbooks, journal articles, magazine articles, thesis, dissertations and then conference papers. Conference papers are reviewed with the least scrutiny and may have mistakes/shortcomings in them.
* Identify recent books in the field and IEEE journal or IEEE magazine articles that review the field (ie. extensive literature survey)
* For papers identified, read and understand abstract, conclusion and skim through body of paper focusing on results obtained
* Filter related literature from non-related literature
* Understand original contribution of papers, summarise main results obtained. Don’t focus on the detailed mathematics as yet.
* Identify core literature that is very relevant to your problem statement or research objectives. Go through the math.
* For core papers, use Google Scholar to find papers that cite each of the core papers. Then read these papers as well.
* Ensure that your literature search contains recent journal/conference papers that are less than 5 years old
* Critically identify gaps in papers, identify limitations + assumptions and aspects not sufficiently addressed
* Explain how your contribution fills the current gap in the literature
* Write up draft literature survey with diagrams/photos and key results/graphs from the literature
* Refine your literature survey to be more engaging, where pertinent issues in the literature are drawn out to justify problem being addressed
* Locate your research in the existing literature: clearly frame any contributions in contexts of these ‘gaps’ in the literature

Notes:
* Setup an alert in Scopus to send you notifications on new publications in your field of interest
* Use tables to summarise and compare details, results and assumptions from various papers/literature
* It will take many drafts to finalise your literature survey for your final submission of your dissertation/thesis. Don’t delay writing your literature survey until the end. Write as you go along, together with the references. As you finalise your dissertation/thesis, you can refine your literature, which is less work than starting from scratch.

== Design process ==
# Write user requirements: assign each one with a unique ID. Write so that a test can be developed to assess if user requirement is met or not. Capture in use case diagram
# Write technical requirements: assign each one with a unique ID. Must have a function and how well the function is being done. Write so that a test can be developed to assess if technical requirement is met or not
# Clarify system being developed using relevant diagrams: sequence diagrams, activity diagrams, block diagrams
# In the block diagram of the system: identify inputs/outputs and major subsystems, identify and label all interfaces between subsystems, identify all external interfaces
# For each major sub-system: identify and explain properties of multiple feasible sub-systems that can work, choose one based on requirements of project
# The design process needs to have a logical flow
# Enough details need to be given in the write-up to allow another student to duplicate the work
# Creative development of design process and meticulous care in the design description

== Practical work ==
# Identify what practical work needs to be done to address research objectives
# Include all hardware, simulation and software and planning of experiments
## Hardware: include schematics, PCB layout
## Simulation: include flow chart and verification tests to build the examiner’s confidence in the accuracy of the simulator
## Software: flow chart and verification tests
## Planning experiments: illustration of experiment showing radar + target (distance from radar to target, etc), list of experiments planned
# Write up should contain enough details for another student to duplicate the work

Note: reference software/hardware done by others that you are using in your work

== Results and discussion on results ==
* Measured data: show ‘simple’ results to show that radar was generating good quality data
* There should be results (ie graphs) that link directly with the research objectives
* Compare the results of your work with the ‘state of the art’ (current algorithms/techniques in the literature)
* Graphs should be clear, font size of labels and numeric values should be big enough to read
* In the graphs, consider annotating important features using arrows and text
* In the discussion of results, make specific reference to figures. Example: In Figure 4.1, ...
* Interpret graph to the reader and explain important trends/features/annotations in graph
* Show insight by explaining why the results were positive or why the results were poor
* Do not make strong conclusions from results obtained using few data points and from only considering one or a few scenarios. This leaves a poor impression in the mind of the external examiner. Rather, generate statistics (mean, variance, etc) from analysing larger number of data points (‘large’ depends on your field/problem) in many scenarios and then make conclusions.
* Demonstrate creative analysis that brings out pertinent solutions to the problem statement and research objectives

== Conclusion and Future work ==
* Conclusion should link directly to research objectives stated in the Introduction
* Conclusion should not include anything new that has not been discussed in the main body of the write-up
* Conclusion should be concise, precise
* Future work: clear and achievable ideas for future research
* Future work: include creative suggestions for future research

= Writing up dissertation/thesis =
* Outline of dissertation: chapter headings, section headings
* Structure of report must have a clear and logical flow, with transition paragraphs to explain when the topic changes
* Ensure you have methodology section/chapter in your dissertation, where the approach used to address the research objectives are clearly outlined.
* Coherency: ensure that each paragraph starts with a topic sentence & contains a single idea
* Language: check spelling, grammar, punctuation. Sentences in past tense. Use third person. Do not use ‘I’, ‘we’, ‘he’, ‘they’
* Graphs: font size of labels, values, legend clear
* Table captions: above table
* Figure captions: below figure
* References: conforms to IEEE referencing style, complete, accurately referenced. Do not forget to reference figures. Generally you want figures to be your own work; figures that are adapted from others (or might be inspired from multiple sources) should be duly referenced. An excellent guide to referencing is available at: [https://aso-resources.une.edu.au/academic-writing-course/information-basics/introduction/ UNE Academic Skills Site]
* Acronyms defined before they are used
* Abstract: write this last. A good abstract should contain the following
** What was done? (what ideas and concepts were investigated?)
** Why was it done? (what was the rationale for the study?)
** How was it done? (How did you do the work? What data was generated and used? What was the origin of the data? How were data gathered? What tests, scales or summary measures were used? In order words, how was the analysis and/or synthesis done?)
** What was found? (What were the conclusions and what were the significant findings)
** What is the significance of the findings? (what difference does it make? What next?)

Note: read many Masters dissertations and PhD thesis in your field. See https://open.uct.ac.za/ for UCT dissertations/thesis. Learn the following: the level of written English expected, the structure of a dissertation/thesis, the flow of the literature survey chapter and how to write-up a good quality critical literature review and how to identify the ‘gap’ in the literature, how to describe algorithms/methods used in the work, discussion and presentation of results, …

= How external examiners mark dissertations/theses =
== Elements of a good quality dissertation/thesis ==
* Clear format, presentation, literature review, theoretical framework of the thesis and the problem of unsubstantiated and over-generalised conclusions.
* A pertinent literature review, clear hypothesis, achievable problem, sound data analysis and methodology and justifiable conclusions
* Dissertation/thesis is consistent and does what they said they were going to do rather than adhere to a particular paradigm or methodology. Examiner’s words “I try to see it from their eyes and whether they have been true to what they set out to do”
* Logically presented, focused, succinct, summarised and in which signposts are used to help readers to understand the path they are taking through the work
* Coherence (the student has done what they said they would do)
* Professionalism: as demonstrated by mature comments and the accuracy of the logic
* A student who makes the ideas his/her own with some originality of presentation
* The development of a well-structured argument (highly valued part of a thesis): Logical progression of ideas, work and presentation, higher level thinking and analysis, the selection of a “real” problem, and a sensible do-able question along with a literature review that tells a story. the student takes you on a journey and “succinct writing without speculation”
* Examiners value students that critically analyses their work: “They are critical of their own argument”
* Examiners are looking for students who are able to work their way through problems: “How they recognise and deal with contradictions"

PhD specific:
* Originality: the original use of a concept or theoretical framework. Novel work opens up new areas
* Sense of a student autonomy or independence (The student makes the ideas their own)
* Sufficient material in the thesis to submit to result in 2-4 good journal articles
* Student shows confidence in the way they dealt with the material and level of sophistication in the way they presented their argument
* When student has generated 2-3 good quality publications, the examiner can ‘put his feet up’ and enjoy the read
* When student has not produced any publication, examiner may question: “that’s interesting”, reflecting on his/her on experience of publishing when he/she was a PhD student

== Typical details of the examination process ==
* Takes 4-5 full-time days to examine a thesis over a period of 2-3 weeks
* First impressions count: initial assessment about whether the assessment of a dissertation/thesis is going to be “hard work” or “an enjoyable read”
* Initial impressions of the quality is usually formed by the end of the 2nd or 3rd chapter of the dissertation/thesis
* If the examiner believes that the student has critically analysed the literature and grasps the problem, then the examiner reads the rest with much more of a sympathetic view and he feels he can relax. If chapter 2 is not good, then he reads the rest much more critically
* Some examiners read chapter 1 and then the last chapter. To check if these two ties up.

== Questions that examiners ask themselves while marking the dissertation/thesis ==
* Sloppiness: typographical errors, mistakes in calculations, referencing and footnotes. Concern: if writing up is sloppy, then the results and conclusions become highly questionable to the examiner
* Lack of coherence
* Lack of understanding of the theory
* Lack of scoping the project in the introduction of the dissertation
* Incomplete description and lacking details for duplicating the results in the work
* Researching the wrong problem
* Work that is not meaningful enough, significant enough or original enough for a PhD thesis
* Not being able to explain at the end of the thesis what has been argued/achieved in the dissertation/thesis
* References that are poor with many references to websites/blogs, poor quality journals and conferences. Lack of references of recent publications which asks the question in the examiners mind: “does the student understand the ‘state of the art’ of the current trends in this broad research topic.

== Elements of a poor dissertation/thesis ==

Make

2021-08-10T12:36:42Z

Swinberg:

[[Category:Software]]
[[Category:Design Tools]]

= Overview =

Make is defined as a "build automation tool" which automatically builds executable programs, libraries or other type of target (desired file) from source code. Usually this desired 'target' is an program that you want to run. For full details on make and makefiles see the official GNU Make documentation at https://www.gnu.org/software/make/manual/make.html.
Make is a way to capture and automate the build process, to capture the compile process, how the generation of intermediate files depend on other files. If you are not already familiar with the reason for using Makefiles in a project you are recommended to read the [https://www.gnu.org/software/make/manual/make.html#Overview Gnu Make Overview].

Makefiles are not limited to just making executables from C / C++ or compiling of code. They can be used for generating other kinds of execution objects which might involve generating some sort of runtime environment in which the exucatable, or executables, run within.

Of course, IDEs often use a makefile or other method of compiling behind the scenes, and you may likely not need to both with needing to edit the makefile itself. The IDE is likely to provide a settings menu where you can specify things like include library paths and compiler options. However, there may still be occasions where you need to manipulate the makefile itself to adjust the method being used to generate you target file(s).

= Planning a Makefile =

The first thing, before you attempt writing a makefile is to know how the application you want to make is generated. Knowing of whatever compilers, assemblers, linkers and other tools to go from the code to an executable. When talking about C and using GCC, the essential thing you should hopefully know already, before you attempt constructing a makefile, is the basics of the gcc command.

Before making a makefile, you should know what tools that are going to be used in the compile process, and the sequencing of these tools for building your executable.

There may be various other commonly used operations, related to the build process, that might not specifically be part of the build process but needed in starting or setting up the build process, the development environment or the execution environment that you are wanting to utilize. An example of such a process is the ‘clean’ process, which deletes any intermediary files (e.g. object files) and the previously compiled executable. Applying the 'clean' process generally forces the build processes to remake the executable from scratch the next time it is run.

Other common make process are:

* ‘mark’: which is not really what tutors use for marking your code (it could be!) but rather some companies use it to make a significant state of the project e.g. mark a build in some way, possibly sending it to a repository.
* ‘backup’: obvious one this. Apply some backup operation, maybe zipping up the project files and uploading it to some file store.
* ‘test’: either generating testing code (sometimes one generates automated testing code, e.g. a separate project that will test your project) and/or runs tests through your already compile application.

To make this page brief and to give you a quick start to makefiles, a simple example of a makefile for compiling a C program is given below. The subsequent section lists some useful tutorials that you may want to explore further to improve your makefile writing skills.

= Examples =

== Simple example makefile ==

To illustrate the process of developing a makefile, let us consider we want to make a program from the following files:
<pre>
test1.c
test1.h
</pre>

i.e. test.c has H-file interface called test.h

We want to compile test1.c with gcc and we want to generate a GDB debugger compatible executable, which needs the -g flag to be specified. We want to call the generated executable test1 (an elf file, not needing extension if done on Linux). We could do this easily with just gcc:
<pre>
gcc -g -o test1 test1.c
</pre>

But this isn’t scalable. And we haven’t captured the information of dependencies and build process (e.g. so future developers or users will see how to build the program).

Let's quickly plan the build method for this. It would be useful to have these two processes available:

* clean process : to deletes all intermediary files and the executable.
* build process (the default process) : generate the executable if any of its dependencies (as in the .c or .h files) have changed since the last attempt at building.

Here is a super simple start for the makefile, although for the sake of explaining a little more, some special variables, such as $@ and $< have been used (to save some typing) and these are explained after the example. Together with what is being done on each line.

<syntaxhighlight lang="make" line='line'>
CC=gcc
# note the -g below for debugging
# and note that hash symbol used for single line comments
CFLAGS=-I. -g

test1.o: test1.c test1.h
$(CC) -c -o test.o $< $(CFLAGS)

test1: test1.o
$(CC) -o $@ $^ $(CFLAGS)

clean:
rm -f -r test1 test1.o
</syntaxhighlight>

Explanation of special variables used in dependency rules:
{| class="wikitable"
|-
! Variable !! Explanation
|-
| $@ || the name of the output to generate, the LHS of the dependency rule.
|-
| $< || filename of first prerequisite in the dependency definition. For the first dependency definition, i.e. in the entry “test1.o: test1.c …” the first prerequisite corresponds to test.c. So to make test1.o it will call the command “gcc -c -o test.o test.c -I. -g”.
|-
| $^ || This corresponds to the filenames of all the prerequisites, separated by spaces. So, for the case “test1: test1.” the command that will be invoked is “gcc -o test1 test1.o -I. -g”.
|}

And you might wonder What is the ultimate target or root target? This is something you can effectively force by using a so-called 'Phoney Targets', explained in [https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html GNU Make documentation]. But if you don't create rules to make the target more explicit, then make will automatically decide (in this case) test1 is the root target, as it is at the base of the dependencies tree (as in there are no entries dependent on test1. And in case you were wondering, 'clean' is not dependent on test1 as test1 is not in its dependency definition, i.e. not listed on the RHS of the dependency definition. So, test1 will be be decided as the file you want to make by default, when calling make with no arguments).

== More involved example using wildcards ==

Makefile demonstrating wildcards and macros

The following makefile snippet shows how you can set up wildcards / regular expressions for making more generalized rules, as well as saving on typing. This example essentially set a rule to say that every o file that the target is dependent on will be generated using the using $CC -c -o command. If there were lots of .o files listed in the OBJ variable you won't need to add additional entries to explain how the compiling of these c files would work, unless they are compiled in some other way from this first case.

<syntaxhighlight lang="make" line='line'>
CC=gcc
# note -g flag used so that GDB debugger can be used
CFLAGS=-I. -g
DEPS = test1.h # list of dependencies for all C files
OBJ = test1.o # list of object files

%.o: %.c $(DEPS)
$(CC) -c -o $@ $< $(CFLAGS)

test1: $(OBJ)
$(CC) -o $@ $^ $(CFLAGS)

clean:
rm -f -r test1 *.o
</syntaxhighlight>

= Recommended Tutorials =