Here you can find instructions for the CTEF laboratory classes. An example lab assignment, T0, is given to be used as a reference.
This repository will be updated whenever needed, so do not think it is set in stone. Moreover, your suggestions and even contributions via the Pull Request mechanism provided by Github are welcome.
In these online laboratory classes, a recent version of the Linux Ubuntu operating system (18.4 or 20.4 versions) is adopted. It is mandatory that you install Ubuntu either on a real or virtual machine. Other Linux flavors may also work but they are not supported in these class. You may use them at your own responsibility.
Git. If not pre-installed, do:
sudo apt install git
Latex full installation:
sudo apt install texlive-full
LibreOffice (open-source alternative to Microsoft Office used only for drawings):
sudo apt install libreoffice
If needed, install more LibreOffice packages as required.
Octave (open-source alternative to Matlab):
sudo apt install octave
sudo apt install octave-symbolic
sudo apt install octave-signal
sudo apt install octave-control
Python 2.7:
This software is usually included in Ubuntu and may be used as an alternative to Octave for theoretical computations.
Ngspice (open-source Spice circuit simulation tool):
sudo apt install ngspice
sudo apt install ngspice-doc
Login or create a Github account if you do not yet own one.
Go to https://github.com/jjts/ist-tcfe.git using a browser.
Click the "Fork" button in the upper-right corner.
You now have a copy of the example repository located at https://github.com/your_github_user/ist-tcfe.git, which is where you will place all your work for the whole semester.
Now you need download a local copy (clone) of your repository:
git clone https://github.com/your_github_user/ist-tcfe.git
Note that you must clone your fork and not the original example repository because you cannot write to it. Now cd into the example T0 lab assignment:
cd ist-tcfe/t0
To run the T0 lab assignment, do
make
This action will generate all drawings, Octave and Ngspice files needed to produce the final report (report.pdf).
To start working on the T1 lab assignment, type
cd .. && cp -r t0 t1 && cd t1
That is, T1 is initially a copy of T0, which you will modify at will. To check the status of your repository clone, do
git status
It will say all directories and files including and below directory t1 are Untracked by git, which is normal at this point.
Do your work modifying t1's contents. After you are done, anybody will be able to reproduce your work by running your top Makefile placed in the t1 directory:
make
To delete every file that is generated by software, except the final report.pdf file, type
make clean
This action guarantees that only source files and report.pdf are kept in the repository. Any other files can be generated and need not be part of the repository. This guarantees that the project can be easily evaluated and other developers can easily continue it.
Some basic notions about bash (the Linux terminal command interpreter) git (digital repository management tool) and make (software automation tool) will be given in the theory classes. Apart from that, the Internet is full of information about these popular tools, if you know how to search.
At this point, you are ready to commit you work in your local clone, and push it to your Github repository so that the instructor can review and evaluate it. To commit your work in your local clone, you need to stage your changes first:
cd .. && git add .
The cd .. command will move you to the repository root, and the git add . command will stage all new and modified files below it. Now do
git status
This action gives you the last chance to review what will be committed. You can un-stage any undesired file with the command
git reset file
Once you are happy with your staged files do the following:
git commit -m "my fabulous commit message"
where my fabulous commit message should concisely and precisely specify the contents of the commit. To see the history of commits type
git log
This command is invaluable for future references and debug actions, so make sure your commit messages are clear enough. If you now do
git status
the tool will report that your local clone is ahead of the remote or upstream, which designate your Github repository, by one commit. To send your changes to your Github repository, do
git push
This action will sync your clone with your remote. Your group colleagues can get your changes in their local clones by typing
git pull
This command will merge your changes in their clones. However, if one of them has modified the same lines of the same file, she will get a merge conflict after the pull request. The following steps can solve merge conflicts:
- edit the conflicting files and find the conflicting parts that are identified by easy to spot markers
- correct the conflicting parts and delete the markers
- save the file
- fix all conflicting files using the above steps
- commit and push your changes
Note that a merge conflict is deemed solved after you commit your changes. Before that git will always report a merge conflict status.
All assignments consist of a circuit to be analysed theoretically and by simulation. You should perform a theoretical and simulation analysis and write a report for the assignement. The report has four parts:
- Introduction
- Theoretical analysis
- Simulation analysis
- Conclusion
This section should state the work's learning objective, describe the circuit to be analysed referring to a figure, and summarise the theoretical and simulation procedures in the following sections. Two to three paragraphs should suffice with a maximum of 250 words.
Drawings must be done using LibreOffice Draw. Like in a real organisation, to promote collaboration and peer review, everybody must use the same tools, no matter if they are not the best ones. The drawings are edited with the Graphical User Interface (GUI) and saved in the OpenDocument format (.odg). Only the source .odg files should be committed, and your Makefile must have a target to convert all .odg files automatically into pdf files to include in the Latex document. The Makefile in the example T0 assignment illustrates this process and should be studied carefully.
For the same reason, Latex must be used to produce text, which, by the way, happens to be the best tool out there for technical writing. Read the example report and figure out how it is set up to be partially automatically generated from data produced by other programs such as Octave and Ngspice.
Theoretical analysis must be supported by the Octave maths tool. All data plots or data tables must be generated by an Octave script, which should also produce the body of the respective Latex tables automatically. This is also illustrated in the lab assignment T0. This procedure ensures that the Octave code and the text are always in sync. The Octave code is placed in the t0/mat/rc.m location and provides a few examples of what you are expected to do with it.
No formulae should be derived in this section. The laboratory classes should use formulae, not derive them. Mathematical derivation, if applicable, is a subject for the theory classes only.
Simulation analysis must be performed using the Ngspice simulation tool. All data plots or data tables must be generated by a Ngspice script, which should also produce the body of the respective Latex tables automatically. This process is also illustrated in lab assignment T0, using the Makefile and bash commands to help. This procedure ensures that the Ngspice code and the text are always in sync. An example simulation script is provided in t0/sim/t0.net. Ngspice is very well documented with extensive support on the internet.
This section should state if the learning objective of the work has been achieved. It should summarise the results of the simulations and their agreement with the theoretical predictions, commenting on any relevant discrepancies indicating the main reasons for them. Two to three paragraphs should suffice with a maximum of 250 words.
Mistakes in the lab reports resulting from carelessly reviewing the document, and especially leaving copied parts of previous reports that do not apply to the current report, will be penalised.