The algoesup library provides support for testing, timing and linting code.
The algoesup library provides support for testing, timing and linting code.
+This documentation is for version 0.3.1.
Simplified testing for Python functions
+Simplified testing for Python functions, see the examples.
@@ -1166,7 +1167,7 @@Tools for measuring and plotting run-times
+Tools for measuring and plotting run-times, see the examples.
@@ -1204,8 +1205,8 @@Print or plot the run-times of different functions for the same inputs.
-time_functions prints or plots the run-times given list of functions and an input
-generator. Inputs are generated based on a starting size and are doubled a specified
+
time_functions prints or plots the run-times given list of functions and an input
+generator. Inputs are generated based on a starting size and are doubled a specified
number of times.
Print or plot the run-times of function for different input cases.
time_cases prints or plots the run-times of a single function using a list of
-different input generators. Inputs are generated based on a starting size and are
+
time_cases prints or plots the run-times of a single function using a list of
+different input generators. Inputs are generated based on a starting size and are
doubled a specified number of times.
If True, print the run-times in text format.
+If True, print the run-times in text format.
Linting tools for Jupyter Notebook environments
+Linting tools for Jupyter Notebook environments.
+See the type checking and linting examples.
diff --git a/docs/search/search_index.json b/docs/search/search_index.json index d5dba30..cc75111 100644 --- a/docs/search/search_index.json +++ b/docs/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Algorithmic Essays","text":"These documents provide guidance to help you write, critique, and share algorithmic essays.
We define algorithmic essays as short reports, with code, that explain and compare alternative approaches to solving a computational problem.
If you\u2019re a student, writing algorithmic essays benefits you in various ways:
If you\u2019re an educator, you can copy our resources from the GitHub repository and adapt them to your course, due to our permissive licence (see below).
Example
We provide some example essays to illustrate what they are.
While many approaches to writing algorithmic essays are possible, we recommend using Jupyter notebooks, the most widely used medium for mixing text and executable code.
If you\u2019re a student on M269, our data structures and algorithms course, you can write an essay with your existing software and share it on the forums.
Get started (M269)
If you prefer a \u2018Google Docs\u2019-like environment for collaborative authoring and commenting on essays, we suggest Deepnote or Google\u2019s Colaboratory (Colab for short):
We have no affiliation, commercial or otherwise, with Deepnote or Google. We chose them based on our comparison of Jupyter notebook platforms.
Get started (Deepnote) Get started (Colab)
"},{"location":"#acknowledgements","title":"Acknowledgements","text":"This project was partly funded by the UK\u2019s Council of Professors and Heads of Computing, under the Special Projects grant scheme, in May 2023.
"},{"location":"#licences","title":"Licences","text":"The code and text in this repository are Copyright \u00a9 2023\u20132024 by The Open University, UK. The code is licensed under a BSD 3-clause licence. The text is licensed under a Creative Commons Attribution 4.0 International Licence.
"},{"location":"coding/","title":"Coding guide","text":"In\u00a0[1]: Copied!from algoesup import test\n\n# function to be tested\ndef absolute_difference(x: int, y: int) -> int:\n \"\"\"Return the absolute value of the difference between x and y.\"\"\"\n return x - y # deliberately wrong, should be abs(x - y)\n\n# fmt: off\n# unit tests in tabular form, one test per row\nunit_tests = [\n # test case, x, y, expected result\n (\"x == y\", 1, 1, 0),\n (\"x > y\", 10, -1, 11),\n (\"x < y\", -1, 10, 11),\n]\n# fmt: on\n\n# run the function on all test inputs and compare the actual and expected outputs\ntest(absolute_difference, unit_tests)\nfrom algoesup import test # function to be tested def absolute_difference(x: int, y: int) -> int: \"\"\"Return the absolute value of the difference between x and y.\"\"\" return x - y # deliberately wrong, should be abs(x - y) # fmt: off # unit tests in tabular form, one test per row unit_tests = [ # test case, x, y, expected result (\"x == y\", 1, 1, 0), (\"x > y\", 10, -1, 11), (\"x < y\", -1, 10, 11), ] # fmt: on # run the function on all test inputs and compare the actual and expected outputs test(absolute_difference, unit_tests)
Testing absolute_difference...\nx < y FAILED: -11 instead of 11\nTests finished: 2 passed, 1 failed.\n
A unit test consists of the input values to pass to your function and the output value you're expecting. The library requires a short descriptive string for each unit test, so that it can indicate which tests failed. The library expects unit tests to be in tabular format: one row per test, and one column for the description, one column for each input, and one column for the expected output. In the example above, the test table is a list of tuples, but it could as well be a list of lists, a tuple of lists, or a tuple of tuples.
You should reuse the test table for all solutions, because they're about the same problem. Here's a correct function that passes all test cases.
In\u00a0[2]: Copied!def absolute_difference_without_abs(x: int, y: int) -> int:\n \"\"\"Return the absolute value of the difference between x and y.\n\n This solution doesn't use the built-in abs() function.\n \"\"\"\n if x > y:\n return x - y\n else:\n return y - x\n\ntest(absolute_difference_without_abs, unit_tests) # same test table\ndef absolute_difference_without_abs(x: int, y: int) -> int: \"\"\"Return the absolute value of the difference between x and y. This solution doesn't use the built-in abs() function. \"\"\" if x > y: return x - y else: return y - x test(absolute_difference_without_abs, unit_tests) # same test table
Testing absolute_difference_without_abs...\nTests finished: 3 passed, 0 failed.\nIn\u00a0[3]: Copied!
%load_ext algoesup.magics\n%load_ext algoesup.magics
(Magics are special commands that can change the behaviour of running a code cell.) You can now turn on type checking as follows.
In\u00a0[4]: Copied!%pytype on\n%pytype on
pytype was activated\n
Words that start with % are special commands ('magics') for IPython, the Python interpreter used by Jupyter notebooks. The %pytype command, provided by our library, activates Google's pytype type checker.
Once the type checker is activated, it checks each cell immediately after it's executed. In this way you can detect and fix errors as you write and run each code cell. Here's an example of what happens.
In\u00a0[5]: Copied!def double(x: int) -> int:\n \"\"\"Return twice the value of x.\"\"\"\n return x * 2\n\ndouble([4])\ndef double(x: int) -> int: \"\"\"Return twice the value of x.\"\"\" return x * 2 double([4]) Out[5]:
[4, 4]
pytype found issues:
The function is executed and produces an output because lists can also be 'multiplied' with an integer, but the type checker detects that line 5 should have passed integers, not lists of integers, to the function. Clicking on the error name in square brackets leads you to pytype's website, with more info.
When a type checker only processes one cell at a time, it is missing the wider context, like the previously defined functions. Therefore, pytype won't spot all type errors. However, some checking is better than no checking.
The type checker adds some seconds to the overall time to run each code cell. You may thus wish to initially turn off the type checking, with %pytype off, and only turn it on after all code is written and tested. You will have to run all cells of your notebook for the type checking to take place.
For a list of all the options for the %pytype command, see the library reference.
%ruff on\n%ruff on
ruff was activated\n
From now on, each cell is automatically linted after it's executed. Here's an example:
In\u00a0[7]: Copied!l = [1, 2, 3]\nif (not 5 in l) == True:\n print(\"5 isn't in the list\")\nl = [1, 2, 3] if (not 5 in l) == True: print(\"5 isn't in the list\")
5 isn't in the list\n
ruff found issues:
lTrue; use if not 5 in l: for truth checks. Suggested fix: Replace with not 5 in l5 with a constant variablenot in. Suggested fix: Convert to not inEvery message indicates the line of the problem.
l can be misread for 1 (one).if (not 5 in l) == True should be simply if 5 not in lEXPECTED_VALUE, instead of literals like 5 that are meaningless to the reader.As this code cell shows, Ruff sometimes suggests how to fix the reported error, but you must consider whether the suggestion is appropriate.
If you don't understand an error message, like the first one, click on the error code in brackets, to get more information from Ruff's website.
Like for type checking, linting one cell at a time means that the linter is unaware of the wider context of your code. For example, in notebooks, variables may be defined in one cell but used in a later cell. As the linter checks each cell separately, it would report an undefined variable in the later cell. We have disabled checks for undefined variables and other checks that would lead to irrelevant error messages in notebooks, which means that genuine undefined variables won't be flagged. But again, some linting is better than none.
If you get errors that you think are irrelevant, you can disable them with the --ignore option: see the library reference.
%allowed on\n%allowed on
allowed was activated\n
Henceforth, after a cell is executed, the allowed linter will list any constructs, modules or built-in types we haven't taught, like this:
from math import pi, sin\n\nprint(f\"\u03c0 is approximately {pi:.5f}.\")\n from math import pi, sin print(f\"\u03c0 is approximately {pi:.5f}.\") \u03c0 is approximately 3.14159.\n
allowed found issues:
We haven't taught the math.sin() function nor f-strings, and allowed reports these.
Any line that ends with the comment # allowed is ignored. This is useful when you don't want the linter to flag a construct that you explain in your essay. For example, adding the comment after print(...) would not report the f-string. Note that the comment makes the tool skip the whole line: if it has several constructs that weren't taught, none of them is reported.
The allowed linter also includes the configuration for TM112, our introductory Computing course, in case you want to use even fewer constructs in your essay. To use that configuration, write %allowed on --config tm112.json. For a list of all the options for the %allowed command, see the library reference.
You can configure the linter with a JSON file that lists the allowed constructs. See the allowed website for instructions.
Deepnote
Rename the allowed.json configuration in the Files section of your project, and adapt it to your course.
def selection_sort(values: list[int]) -> list[int]:\n \"\"\"Return a copy of the values, in ascending order.\"\"\"\n result = values[:]\n for current in range(len(result) - 1):\n # select the smallest element in result[current:] ...\n smallest = current\n for index in range(current + 1, len(result)):\n if result[index] < result[smallest]:\n smallest = index\n # ... and swap it with the current element\n result[current], result[smallest] = result[smallest], result[current]\n return result\ndef selection_sort(values: list[int]) -> list[int]: \"\"\"Return a copy of the values, in ascending order.\"\"\" result = values[:] for current in range(len(result) - 1): # select the smallest element in result[current:] ... smallest = current for index in range(current + 1, len(result)): if result[index] < result[smallest]: smallest = index # ... and swap it with the current element result[current], result[smallest] = result[smallest], result[current] return result In\u00a0[11]: Copied!
def ascending(n: int) -> tuple[list[int]]:\n \"\"\"Return a list of n integers in ascending order.\"\"\"\n return (list(range(1, n + 1)),) # trailing comma to make it a tuple\n\ndef descending(n: int) -> tuple[list[int]]:\n \"\"\"Return a list of n integers in descending order.\"\"\"\n return (list(range(n, 0, -1)),)\ndef ascending(n: int) -> tuple[list[int]]: \"\"\"Return a list of n integers in ascending order.\"\"\" return (list(range(1, n + 1)),) # trailing comma to make it a tuple def descending(n: int) -> tuple[list[int]]: \"\"\"Return a list of n integers in descending order.\"\"\" return (list(range(n, 0, -1)),)
We should of course test these functions, to make sure they produce the expected lists, but we will skip that in this explanation because we're focusing on how to measure run-times.
In\u00a0[12]: Copied!from algoesup import time_cases # allowed\n\ntime_cases(selection_sort, [ascending, descending], start=100, double=4)\nfrom algoesup import time_cases # allowed time_cases(selection_sort, [ascending, descending], start=100, double=4)
Run-times for selection_sort\n\nInput size ascending descending \n 100 200.5 189.1 \u00b5s\n 200 674.9 702.6 \u00b5s\n 400 2925.2 3016.7 \u00b5s\n 800 12291.2 12540.3 \u00b5s\n 1600 47123.4 47894.4 \u00b5s
Running selection sort on lists from 100 to 1600 integers takes about 170 microseconds to 45 milliseconds. To measure precisely such small time spans, function f (here, selection_sort) is called multiple times on the same input, within a loop, and the total time is divided by the number of iterations, to obtain a better estimate of the time taken by a single call to f. The whole process is repeated 3 times, because the run-times will vary due to other processes running on the computer. The lowest of the 3 run-times is reported.
Because function f is called multiple times, it is very important that f does not modify its inputs. For example, if selection_sort sorted the list in-place, instead of returning a new list, then the first call would put the numbers in ascending order, and the subsequent calls would just try to sort an already sorted list, swapping no numbers. We would obtain almost exact same times for ascending and descending input lists, instead of always larger times for descending lists, as shown above.
When executing a code like the previous one, be patient while waiting for the results. Even though each call may just take a few milliseconds or less, the code cell will take several seconds or even minutes to execute, because the function is called many times to make the measurements more robust.
In\u00a0[13]: Copied!from algoesup import time_functions # allowed\n\ntime_functions([selection_sort, sorted], descending, start=100, double=4)\nfrom algoesup import time_functions # allowed time_functions([selection_sort, sorted], descending, start=100, double=4)
Inputs generated by descending\n\nInput size selection_sort sorted \n 100 174.2 0.5 \u00b5s\n 200 664.7 0.8 \u00b5s\n 400 2812.4 1.6 \u00b5s\n 800 11663.4 3.0 \u00b5s\n 1600 45949.8 6.1 \u00b5s
As expected, the built-in sorting implementation is much, much faster.
In\u00a0[14]: Copied!time_cases(sorted, [ascending, descending], 100, 4, text=False, chart=True)\ntime_cases(sorted, [ascending, descending], 100, 4, text=False, chart=True) In\u00a0[15]: Copied!
time_functions([sorted, selection_sort], ascending, 100, 4, chart=True)\ntime_functions([sorted, selection_sort], ascending, 100, 4, chart=True)
Inputs generated by ascending\n\nInput size sorted selection_sort \n 100 489.6 169226.5 ns\n 200 803.1 649820.8 ns\n 400 1510.5 2802905.0 ns\n 800 2902.1 11221960.4 ns\n 1600 5615.1 45070266.6 ns
The 1e7 above the y-axis means that the run-times must be multiplied by 10\u2077, i.e. 10 million.
Note that when calling time_functions([selection_sort, sorted], ...) in the previous section, the run-times were reported in microseconds, but when calling time_functions([sorted, selection_sort], ...) in this section, they were in nanoseconds. The reason is that the library chooses the time unit based on the first run-time measured. If there's a big time difference between the fastest and slowest cases or algorithms, you may wish for the first function in the list to be the slowest one, to report it with small values in a 'large' time unit, instead of very large values in a 'small' time unit. So, in time_functions([f1, f2, ...], case, ...) the slowest function should be f1, and in time_cases(f, [case1, case2, ...], ...) the worst case should be case1.
This document provides guidance on how to write code for your essay.
"},{"location":"coding/#code","title":"Code\u00b6","text":"Your code should be correct, simple, and as readable as possible. Unless the aim of your essay is to discuss advanced Python constructs, try to use only a basic subset of the language. This allows more people, including those with limited knowledge of Python, to understand your code. It also makes your code easier to port to other programming languages.
We recommend the following workflow, which is further explained in the following subsections.
Writing the tests (step 1) before the code they test (step 2) is a cornerstone of test-driven development, a widely used practice. Thinking of the tests early in the process helps you better understand the problem and think of correct solutions.
Info
If you followed our 'getting started' instructions, the software mentioned in the next subsections to carry out the above workflow is already installed.
"},{"location":"coding/#testing","title":"Testing\u00b6","text":"You should write tests for each function, to have some assurance that it is correct. Tests that check the behaviour of a single function are called unit tests. The unit tests should cover normal cases and edge cases: extreme input values and inputs that lead to extreme output values.
For each input, the smallest possible value, e.g. zero or the empty list, is an edge case, and so is the largest possible value, if there is one for that input. If a function is doing a search for an item in a list, then edge cases would be the item being at the start, at the end, or not occurring at all. If the output is a list, then inputs that produce the empty list are edge cases too. In summary, try to think of the 'trickiest' inputs the algorithm has to cope with.
We provide a small library to support algorithmic essays: algoesup. It allows you to easily write and run unit tests. Here's an example. (The # fmt: off and # fmt: on lines will be explained later.)
As the above examples show, your code should contain type hints like x: int and ... -> int to indicate the type of the input and of the output. They make your code easier to understand, and help type checkers detect any type mismatches, like passing a string instead of an integer.
Tip
The mypy type checker provides a handy summary of Python's type hints.
To type check each code cell of your notebook, you must first load an extension included in the algoesup library.
Note
This subsection only applies to Deepnote.
Once you have written, tested and type checked all your code, you should format it so that it follows the Python community's code style. You will need to format each cell, as explained here.
If there's a block of code that you don't want the formatter to change, write # fmt: off on its own line before the block and write # fmt: on after the block, to temporarily switch off formatting for that block. This feature is especially useful for keeping the format of unit test tables, as shown in an earlier example.
The Deepnote formatter automatically enforces simple formatting conventions, like 4 spaces for indentation and 2 empty lines between functions, so you will see fewer warnings in the next stage.
Info
We suspect Deepnote enforces Black's code style.
"},{"location":"coding/#linting","title":"Linting\u00b6","text":"You should lint your code, which means to check it for style violations.
Tip
You may wish to skim at some point the Python code style and docstring conventions.
"},{"location":"coding/#code-style","title":"Code style\u00b6","text":"Our library supports Ruff, the fastest Python linter. To turn it on, write the following after loading the algoesup.magics extension.
Our library also supports the allowed linter, created by ourselves. It checks whether your code only uses a certain subset of the Python language. This gives you some reassurance that your code will be understood by a wide audience.
By default, allowed checks against the Python subset used in our algorithms and data structures course. So, if you're an M269 student, to check that your essay is easily understood by your peers in terms of Python constructs, just add the following after loading the extension:
Complexity analysis gives an indication of how the run-times will grow as the inputs grow, but it can't predict the exact run-times nor which algorithm is in practice fastest.
Our library helps measure and plot the run-times of one function on different kinds of input, or of different functions on the same inputs.
For example, let's suppose our essay is about sorting algorithms and we have implemented selection sort.
"},{"location":"coding/#generating-inputs","title":"Generating inputs\u00b6","text":"To measure the run-times of sorting algorithms on increasingly large lists, we must implement functions that generate such lists. For example, we can write a function that generates lists that are already in ascending order, which is a best case for many sorting algorithms, and a function that generates lists that are in descending order, which is a worst case for some sorting algorithms.
The library expects such input-generating functions to take a non-negative integer n, and to produce a tuple of input values, with total size n. Why a tuple? Although our sorting algorithm takes a single input (a list of integers), many algorithms take more than one input. Thus the input-generating functions must generate a tuple of inputs, in the same order as expected by the algorithm.
"},{"location":"coding/#comparing-cases","title":"Comparing cases\u00b6","text":"To measure the run-times of a function f on best, average and worst case inputs, use library function time_cases(f, [case1, case2, ...], s, d). The second argument can be a list (or tuple) of up to 6 input-generating functions. The time_cases function works as follows.
case1(s) to generate inputs of size s for f.f on the generated inputs and measure its run-time.case2, ....s to double its value and go back to step 1.The whole process stops when s has been doubled d times. If d is zero, the run-times are only measured for size s.
Here's how we could measure the run-times for selection sort on ascending and descending lists. (The algoesup library is not part of allowed's default configuration, so we must explicitly allow importing it.)
Our library also allows you to compare different algorithms for the same input case. For that, use time_functions([f1, f2, ...], case, s, d), which does the following:
case(s) to generate inputs of total size s.f1, f2, etc. on the generated inputs and measure their run-times.s and go to step 1, unless s has been doubled d times.The run-times are measured as for time_cases: take the best of 3 run-times, each obtained by calling the function within a loop and dividing the total time by the number of iterations.
Here's a comparison of the built-in sorted function against selection sort, on descending lists.
If you add argument chart=True to time_cases or time_functions, then you will see a line chart of the run-times, in addition to the exact run-times. If you only want to see the chart, then add arguments text=False, chart=True.
If, as the input size doubles, the run-times...
Looking at the run-times reported in the previous subsections, we can see that sorted is linear because the run-times about double when the input size doubles, whereas selection sort is quadratic because the run-times increase about 4-fold when the input size doubles.
Remember that run-times vary every time you execute a cell because the computer is executing other processes. This may lead to the odd behaviour here and there. For example, we have noted that sorted is occasionally faster for descending lists, which is counter-intuitive because it does have to reverse them.
If you can't see any trend in the run-times, or they aren't what you expect, one possible cause is that the input sizes are too small. Increase start and run again the code cell.
If after increasing the start size several times you still don't get the run-times you expect from your complexity analysis, then there might be other explanations:
For an example of the latter, see the Jewels and Stones essay.
"},{"location":"coding/#final-check","title":"Final check\u00b6","text":"Once you finished your code, check your essay.
"},{"location":"deepnote-background/","title":"Background","text":""},{"location":"deepnote-background/#organisation","title":"Organisation","text":"Deepnote uses an organisational framework with three major parts: workspaces can contain multiple projects and each project can contain multiple notebooks and files.
The workspace is the highest level structure in Deepnote, and is designed to group related Projects and enable team collaboration. Every user can create their own workspaces where they can manage access, set permissions and oversee projects. A workspace can have multiple members each with their own access permissions, but by default they can see all projects in the workspace.
Projects are the next tier down from workspaces in terms of organisation and provide the main working environment as well as the integrated file system. When you duplicated our project, you duplicated all of the notebooks, files and the environment too.
Notebooks are akin to Jupyter notebook. They are interactive documents that combine executable code with richly formatted text and visualisations. Notebooks are where you will write your essays.
"},{"location":"deepnote-background/#deepnote-vs-classic-notebook","title":"Deepnote vs Classic Notebook","text":"Notebooks in Deepnote have similar functionality to classic Jupyter notebooks in that they combine rich text, visualisations and executable code in a single document. But there are a few notable differences in the UI and functionality worth mentioning.
Firstly, Deepnote is a cloud-based Jupyter notebook platform: this means no local software installation is required to get started. It also means you can access your documents from anywhere with an internet connection. This is a double edged sword of course, if you lose your connection you lose access to your notebooks.
In Deepnote the divisions within a notebook are referred to as \u201cblocks\u201d instead of \u201ccells\u201d, but we will continue to use the classic terminology. Deepnote retains the same structure of code and markdown cells as used in Jupyter notebook, but it also provides additional cell types. Besides cells for data science, Deepnote adds rich text cells. Unlike standard Jupyter notebooks, these cells offer a what you see is what you get (WYSIWYG) text editing experience, similar to applications such as MS word and Google Docs. They include spellchecking and the usual formatting shortcuts like Ctrl + B for bold, Ctrl + I for italics, and so on. Rich text cells can be advantageous if you plan to use Deepnote exclusively as they can simplify the writing process. However, it is important to note that any formatting from rich text cells will not be preserved if you download your notebook. So if you plan to use your notebooks on other platforms it is advisable to stick to Markdown cells for writing text.
Finally, there is a key difference in the way Deepnote and Jupyter handle Markdown. Normally to create a line break in Markdown, either a double space followed by the Enter key, or a backslash followed by the Enter key is required. This is the approach followed by Jupyter Notebook and many other notebook interfaces. Deepnote, however, does it differently, simply pressing Enter creates a line break without the need for explicit characters like double space or backslash. This alternative approach is a deviation from the Markdown standard and affects how rendered Markdown looks when moving between platforms.
"},{"location":"deepnote-background/#collaboration","title":"Collaboration","text":"Deepnote was designed with collaboration in mind and offers several features to do this which are not found on some other platforms.
Users in Deepnote can work together on projects simultaneously: any changes made to files and notebooks within the project can be seen instantaneously by both parties. Real time collaboration works best when you are also communicating in real time with your peers, say for example, using Zoom, Teams, Discord or WhatsApp.
Additionally Deepnote offers the option for asynchronous communication through comments. Comments can be left in a specific cell and are visible by anybody viewing the notebook. The first comment made in a cell opens a new thread, and anyone commenting in a thread receives email notifications after a new message is posted. Open threads can be resolved to hide them and save space; threads can be reopened if needed. Any open threads are displayed in a main comments panel on the right-hand side of a project.
Comments are one of the ways to give and receive feedback on your essays. See the feedback guide for more details.
"},{"location":"deepnote-background/#limitations","title":"Limitations","text":"As noted at the start of the guidance, Deepnote was selected as the platform for the Learning Professional Skills with Algorithmic Essays project due to its simple interface, customisable environment, and features for collaborative working. However, it is important to acknowledge and assess its limitations.
As mentioned above, Deepnote deviates from Jupyter Notebook by having new types of cell such as rich text cells. It also handles Markdown in an different way from most other platforms. This has implications for how your notebooks will be rendered using different jupyter interfaces. The same notebook could look different on other platforms compared to Deepnote; the length of text lines might be different and some of the formatting may be altered or lost.
In addition to this, when working on a cloud-based platform such as Deepnote, executing cells can sometimes feel slow, especially when the virtual machine has been idle for a while. Furthermore, an issue has been observed when a Markdown cell contains an excessive amount of text, which appears to slow down performance, potentially due to the autocomplete functionality.
As a final point, the way Deepnote stores notebooks within the environment must be mentioned. You can of course upload a notebook to the system and access it like any other file, but if you want to run the notebook, it must be moved to the NOTEBOOKS section. This then becomes a problem if you wish to access the notebook file again, say using the terminal. When a notebook is moved to this section it effectively takes the notebook out of the integrated file system and locates it to a separate database which the user no longer has access to.
"},{"location":"deepnote-how-to/","title":"Deepnote how-to guides","text":""},{"location":"deepnote-how-to/#account-operations","title":"Account operations","text":""},{"location":"deepnote-how-to/#sign-up-for-deepnote","title":"Sign up for Deepnote","text":"This is explained in our Getting Started guide.
"},{"location":"deepnote-how-to/#log-in","title":"Log in","text":"If you have logged out, to log back in you need to verify your email again:
Before any of the following operations, you must change from project view to workspace view:
You will now see a list of the projects in your workspace: Some projects were automatically added by Deepnote when creating your workspace.
After you completed the desired workspace operations, click in the side panel on the project you want to work next.
"},{"location":"deepnote-how-to/#enable-sharing","title":"Enable sharing","text":"For notebooks, the download operations are called Export as .ipynb and Export as .pdf. If your notebook contains other types of cells besides Markdown and code, the downloaded .ipynb file won\u2019t be rendered correctly on other Jupyter platforms.
This is explained in our Getting Started guide.
"},{"location":"deepnote-how-to/#share-your-project","title":"Share your project","text":"The following assumes you have enabled sharing for your workspace.
The simplest way is to drag the notebook or file from your desktop to the Notebooks or Files section in the side panel.
Alternatively, to upload a file:
To perform an action on a cell, do one of the following:
Running a cell executes the code or formats the Markdown text.
To run one cell, do one of the following:
To run all cells, click Run notebook in the top right corner of the notebook.
Note
The first time you run code, it will take some time, because Deepnote must first start a server with the necessary software.
"},{"location":"deepnote-how-to/#add-a-cell","title":"Add a cell","text":"To insert a cell between two existing cells:
c followed by Enter.m followed by Enter.To append a cell, scroll down to the end of the notebook and do one of the following:
Do one of the following:
Do one of the following:
After typing your comment, press the upwards blue arrow to finish.
Warning
You must be logged into your account to comment on notebooks shared with you. If you\u2019re not logged in, your comments are marked as \u2018anonymous user\u2019 and the essay\u2019s author won\u2019t see them.
"},{"location":"deepnote-how-to/#format-a-code-cell","title":"Format a code cell","text":"This \u2018pretty prints\u2019 the code. Do one of the following:
f in the search box of the menu.)Note
Formatting takes 1-2 seconds and adds an empty line (which you may delete) to the end of the cell.
Warning
If you get a message \u2018parsing failed\u2019, then the code cell is not valid Python and can\u2019t be automatically formatted. This may happen if the cell has IPython commands starting with %.
The workspaces interface provides an overview of any projects in your Workspace. On the left-hand side panel you will find a navigation menu allowing you to quickly navigate to different sections of your workspace. Starting from the top, the sections are:
Integrations - This section allows you to set up and manage connections to data sources. This is mostly used for data science work.
Settings & members - Manage who has access to the workspace and its resources.
A project\u2019s interface has similarities to the interface for your workspace. Starting from the top, the sections on the left-hand side panel are:
Notebooks in Deepnote have the same core functionality as Jupyter Notebooks: they combine executable code and text in the same document.
See Deepnote vs Classic Notebook for some differences between the two.
"},{"location":"deepnote-reference/#access-levels","title":"Access levels","text":"Access levels are the range of permissions or capabilities assigned to a user in Deepnote. They differ between the contexts of workspaces and projects.
The access levels for projects are:
The access levels for workspaces are:
Editor: Editors can create and edit workspace projects.
Admin: Admins have all access rights, including permission to manage workspace members.
Cells (called \u2018blocks\u2019 in Deepnote) are the divisions within each notebook. They are a distinct area where code or text can be added depending on the type of the cell. See our how-to guide for working with cells.
"},{"location":"deepnote-reference/#terminal","title":"Terminal","text":"A terminal will give you a command line interface for your project and runs a bash shell.
Launching a Terminal in Deepnote allows you to run scripts or complete tasks where the GUI is not suitable.
See the Deepnote documentation on terminals for more information.
"},{"location":"deepnote-reference/#environment","title":"Environment","text":"The environment refers to the setup and configuration that supports the execution of code within your project.
The code in each project runs on a virtual machine which is an isolated computing environment with its own CPU memory and storage resources. These specifications can be adjusted in a limited way if required and various software packages can be added to your environment to suit your needs.
When you copied our project, you also copied the environment.
See Deepnote\u2019s documentation on custom environments for more information.
"},{"location":"deepnote-reference/#real-time-collaboration","title":"Real-time collaboration","text":"Real time collaboration refers to the capability of multiple users to work on the same documents in the same project at the same time. Any changes to documents can be seen by all users working on the project as and when they happen.
See Deepnote\u2019s documentation on real-time collaboration for more details.
"},{"location":"deepnote-reference/#asynchronous-collaboration","title":"Asynchronous collaboration","text":"Asynchronous collaboration is a method of working where users do not have to be working at the same time. Users can contribute to projects and documents at their own pace to suit their own schedule.
The main tool for asynchronous collaboration in Deepnote is the comments system. Users can comment on code and text in the corresponding cells to communicate with peers.
"},{"location":"deepnote-reference/#command-palette","title":"Command palette","text":"The command palette provides quick access to all of the files in a project and the most popular actions.
You can open and close the command pallet by pressing Cmd + P on Mac or Ctrl + P on Windows.
"},{"location":"deepnote-reference/#members","title":"Members","text":"A member is a Deepnote user associated with a particular workspace.
When a user is a member of a workspace, they typically have access to all the projects within that workspace, but the access permissions can be adjusted.
Projects do not have members, but you can give or be given access to a project with certain permissions. See Access levels for more information.
"},{"location":"deepnote-reference/#markdown-cheat-sheet","title":"Markdown cheat sheet","text":"Feature Syntax/Example Headers H1 Header# H1 Header H2 Header ## H2 Header H3 Header ### H3 Header H4 Header #### H4 Header H5 Header ##### H5 Header Code Inline Code `Code` Code Block ```Code block``` Formatting Italic _italic_ or *italic* Bold **bold** or __bold__ Strikethrough ~~strikethrough~~ Links External Link [Google](https://www.google.com) Section Link [Top](#top) Lists Bulleted List - List item Numbered List 1. List item Math Inline Math $x=1$ Math Block $$$x=1$$$ Other Quote > Quote Divider --- HTML <h1>Title</h1>"},{"location":"deepnote-reference/#keyboard-shortcuts","title":"Keyboard shortcuts","text":"Deepnote has many keyboard shortcuts for quickly performing typical actions on cells and text.
General
MAC WINDOWS & LINUX ACTION \u2318 + P ctrl + P Show/Hide command paletteBlock Actions
MAC WINDOWS & LINUX ACTION \u21e7 + \u21b5 shift + enter Run current block and move cursor to next block (creates a new cell if at the end of the notebook) \u2318 + \u21b5 ctrl + enter Run current block \u2318 + \u21e7 + . ctrl + shift + . Stop execution \u2318 + \u21e7 + H ctrl + shift + H Hide/Show block output \u2318 + \u21e7 + M ctrl + shift + M Toggle between code and Markdown block \u2318 + \u21e7 + \u232b ctrl + shift + backspace Delete block \u2325 + \u21e7 + \u2191 alt + shift + \u2191 Move block up \u2325 + \u21e7 + \u2193 alt + shift + \u2193 Move block down \u2318 + \u21e7 + D ctrl + shift + D Duplicate block \u2318 + J ctrl + J Add new code block below current one \u2318 + K ctrl + K Add new code block above current one \u2318 + Z ctrl + Z Undo \u2318 + \u21e7 + Z ctrl + shift + Z RedoCode Editing
MAC WINDOWS & LINUX ACTION \u2318 + D ctrl + D Expand selection (multiple cursors) tab tab When caret is at the beginning of a line, add indent; otherwise, show autocomplete suggestions \u21e7 + tab shift + tab Decrease indent \u2318 + / ctrl + / Toggle line/selection comment \u2325 + \u2193 alt + \u2193 Move lines down \u2325 + \u2191 alt + \u2191 Move lines upTerminal
MAC WINDOWS & LINUX ACTION \u2318 + C ctrl + shift + C Copy selected text \u2318 + V ctrl + shift + V Paste"},{"location":"deepnote/","title":"Deepnote","text":"Deepnote is the cloud based Jupyter notebook platform we recommend for writing your essays.
The platform was chosen due to its simple interface, customisable environment, and features for collaborative working.
Warning
This Deepnote guide is limited in scope to the writing, sharing and critiquing of algorithmic essays. There are many features of the platform not covered here. See the official documentation for more extensive coverage.
You may find it helpful to watch the following introduction video.
This guide has three parts:
Note
Use the side panel to navigate the Deepnote guidance.
"},{"location":"example-essays/","title":"Example essays","text":"These examples illustrate different ways of structuring essays and different writing styles.
For some essays, there\u2019s a template that highlights the essay\u2019s structure and the purpose of each section. These templates help you start writing your own essay. Clicking on a button below will open a read-only version of the essay or template.
To get an editable version of a template to start writing your own essay, right-click on a download button. From the pop-up menu, choose \u2018Save file as\u2026\u2019 (or similar) to save the template in a folder of your choice.
Deepnote
You don\u2019t need to download anything because you will have the essay templates and examples once you copied our essay project, as explained in Getting started (Deepnote).
Colab
You don\u2019t need to download any template because you can open them directly, as explained in Getting started (Colab).
"},{"location":"example-essays/#sum-of-1-to-n","title":"Sum of 1 to n","text":"This is a short and simple essay, suitable for those on introductory programming courses. The essay shows two ways of calculating 1 + 2 + \u2026 + n and compares their run-times. The essay follows a simple structure, in which each approach is outlined, implemented and tested before moving on to the next one.
Essay Template Template (download)
"},{"location":"example-essays/#jewels-and-stones","title":"Jewels and Stones","text":"This is a longer essay, for those on data structures and algorithms courses. The problem is to count how many characters of a string occur in another string. The essay solves the problem in three ways, with linear search, a set, and a bag/multiset. The complexity of the three algorithms is analysed and compared to their run-time.
This essay follows a slightly different structure, in which each approach is outlined and its complexity analysed, before deciding which approaches are worth implementing.
Essay Template Template (download)
"},{"location":"example-essays/#two-sum-two-approaches","title":"Two Sum (two approaches)","text":"This classic problem asks to find two numbers in a list that add up exactly to a given number. This essay solves the problem in two ways, with brute-force search (nested loops) and a map (Python dictionary).
Essay
"},{"location":"example-essays/#two-sum-three-approaches","title":"Two Sum (three approaches)","text":"This is an extended version of the previous essay. It adds a third approach, that sorts the list of numbers.
Essay
"},{"location":"feedback/","title":"Feedback guide","text":"Giving feedback on each other\u2019s essays is an important part of developing professional skills with algorithmic essays.
Receiving feedback helps improve your essay, while giving feedback helps develop your communication skills. Moreover, reading other people\u2019s essays is a great way to learn more about Python, algorithms, data structures, code style, etc.
Feedback is part of professional software development practices. Many companies and open source projects have formal code reviews, in which developers must submit their code for inspection by others. Code reviews help increase the quality of the code, share best practices among developers, and on-board new developers.
Many companies use pair programming, in which two developers work together on the same piece of code. While one writes the code, the other reviews it as it\u2019s written, pointing out mistakes and suggesting improvements. The two developers switch roles often during a pair programming session. With Deepnote and Colab, you and someone else can work simultaneously on the same notebook, while using Zoom, Microsoft Teams or some other app to chat.
In summary, by engaging in a feedback process for your and others\u2019 essays, you will develop valuable professional skills.
"},{"location":"feedback/#asking-for-feedback","title":"Asking for feedback","text":"You can ask for feedback at any point during the production of your essay, not just when you have a complete draft. You will have to tell others what kind of feedback you want.
For example, if you\u2019re undecided between three problems, you may write a notebook that just describes the problems and asks others to choose one of them, by including something like:
Please help me choose a problem to tackle. Which of the previous problems would you like to see solved and why?
It helps the reader if the request for feedback stands out from the remaining text. You may prefer to use bold, italics, or HTML to format it differently.
You can also ask for feedback after choosing a problem and thinking of some algorithms, but before investing the time in implementing and testing them. Your request could be:
I\u2019m looking for feedback on the above algorithms. Are they clear? Have I missed other approaches to solving this problem?
Once your notebook is ready for feedback, you need to share it so that others can comment on it. You may invite comments from anyone or only from one or two \u2018essay buddies\u2019: they comment on your essay and you comment on theirs.
Info
For how to share your essay, see the corresponding instructions for Colab, Deepnote or M269.
"},{"location":"feedback/#giving-feedback","title":"Giving feedback","text":"Once you have been invited to comment on an essay, read it as soon as you can, because the author is waiting for it to progress the essay to the next draft.
Feedback should be specific and constructive. Generic comments like \u201cThis is confusing\u201d or \u201cI don\u2019t understand this\u201d aren\u2019t helpful for the author. State what you\u2019re finding hard to grasp, like:
Before adding a comment to a notebook cell, read the existing comments, to avoid repeating the same points others have made.
Comments that aren\u2019t about a specific text paragraph or code cell, but rather about the whole essay, e.g. its structure, should be attached to the first cell, with the essay\u2019s title, or to the last cell.
The author has put effort into their essay, and will appreciate encouraging feedback to keep polishing it. For example, if you commented on a previous version, praise the parts that improved.
"},{"location":"feedback/#acting-on-feedback","title":"Acting on feedback","text":"Deepnote emails every time you get a comment on your essay. You may wish to improve your essay as you get each piece of feedback, or you may wait some time, e.g. a week, to collect a variety of comments and then address them in one pass.
As you scroll down your essay, look for speech bubble icons. Click on them to see the comment thread associated to that cell. Once you modify the cell to address those comments, mark the thread as resolved.
Don\u2019t feel obliged to follow every suggestion you receive. The reviewers of your essay may present contradictory suggestions and some may take too much effort to address.
If you don\u2019t understand a reviewer\u2019s comment, add a comment yourself, asking them for clarification. Be specific, explaining what you don\u2019t understand. Alternatively, rephrase the reviewer\u2019s comment and ask them to confirm your interpretation, e.g. \u201cDo you mean I should rename the variable from \u2026 to \u2026?\u201d
"},{"location":"feedback/#crediting-feedback","title":"Crediting feedback","text":"You should acknowledge who provided input, by adding a section at end of your essay with something like this:
I thank my tutor Jane Doe and my fellow students John Smith and Carla Suarez for feedback that helped improve this essay.
Crediting others allows them to point to your essay to provide evidence, e.g. to prospective employers, of giving feedback others find useful. It\u2019s therefore best if you can be specific about each one\u2019s contribution, in particular if someone provided some of the content, beyond just commenting. Content contributions should be mentioned before feedback. For example:
I thank John Smith for analysing the complexity of the second approach. Jane Doe helped me improve the structure of this essay. Carla Suarez spotted several typos and suggested improvements to the code style.
It\u2019s easiest to keep track of contributions if you update the acknowledgements as you act upon feedback. You may wish to offer co-authorship of the essay to those who made substantial contributions.
The acknowledgments should also mention if your solutions are based on someone else\u2019s, unless you already said so when introducing the algorithms. For example:
The second algorithm was taken from the solution posted by LeetCode user soandso, but the code is my own. The third algorithm and implementation are based on user123\u2019s solution. I thank \u2026
When possible, the acknowledgement text should link directly to the original solutions.
If the code or tests were partly or wholly written by generative AI, say so, preferably indicating the prompts you used.
"},{"location":"getting-started-google-colab/","title":"Getting started (Google Colab)","text":"Follow these steps to start writing essays on Google Colab within a few minutes.
"},{"location":"getting-started-google-colab/#copy-an-essay-template","title":"Copy an essay template","text":"Important
To use Colab, you need a Google account. To create one, visit the Google Account sign in page and follow the instructions.
Info
The first code cell of each template essay notebook installs the necessary software when running the notebook in Colab.
"},{"location":"getting-started-google-colab/#write-the-essay","title":"Write the essay","text":"Now that you have saved and renamed a copy of the template, you can start writing your essay in Colab.
For how to use Jupyter notebooks in Colab, read through the Overview of Colaboratory Features.
For guidance on writing algorithmic essays, see our writing and coding guides.
"},{"location":"getting-started-google-colab/#share-the-essay","title":"Share the essay","text":"When you are ready to share the essay with others, do the following:
For suggestions on how to ask for feedback on your shared essay, see our feedback guide
"},{"location":"getting-started-google-colab/#comment-on-essays","title":"Comment on essays","text":"Once an essay has been shared with you, you can comment on it. See our guide on how to leave feedback.
In Colab, comments are attached to a cell and are displayed next to the cell they refer to.
If you have edit or comment permissions, you can comment on a cell in one of three ways:
You can resolve and reply to comments, and you can target comments to specific collaborators by typing @[email address] (e.g., @user@domain.com). Addressed collaborators will be emailed.
The Comment button in the top-right corner of the page shows all comments attached to the notebook.
"},{"location":"getting-started-m269/","title":"Getting started (M269)","text":"If you\u2019re an M269 student, follow these steps to start writing essays within a few minutes.
"},{"location":"getting-started-m269/#install-software-optional","title":"Install software (optional)","text":"While you can write essays with your current M269 software, we recommend installing two more packages to help you test, check the style, and measure the run-time of code.
m269-23j.(m269-23j) ... and you should be in your M269 folder.To install the software, enter pip install algoesup ruff in the PowerShell / terminal.
Note
You also need the most recent version of allowed, which is available from the Resources tab of the M269 website.
We have created templates to serve as starting points for your essay.
essay-Michael.ipynb) or that indicates the topic (e.g. balanced-brackets.ipynb). If you prefer, you can rename the file later, when you settled on a topic.With the essay template in your M269 folder, you can work on it in the same way you do with the book\u2019s chapters and your TMAs.
m269-23j to activate your M269 environment and go to your M269 folder.nb to open the Jupyter dashboard, from which you can open the essay.For guidance on writing algorithmic essays see our writing and coding guides.
"},{"location":"getting-started-m269/#share-the-essay","title":"Share the essay","text":"Once you have a draft you want others to give feedback on, make a post in the VLE forum corresponding to the topic of your essay, and attach your notebook file.
For example, if your essay is about ordered or unordered collections, post it in the Weeks 1-10 forum, but if it also uses recursion or a sorting algorithm, post it in the Weeks 11\u201320 forum.
Once you have addressed others\u2019 feedback, post the final version of your essay, acknowledging the commenters.
"},{"location":"getting-started-m269/#publish-the-essay-optional","title":"Publish the essay (optional)","text":"If you want to publish your essay outside the M269 forums, you have several options.
algoesup GitHub repository, with a link from the example essays page. The copyright of your essay remains with you.Follow these steps to start writing essays within a few minutes, without any software installation or configuration.
"},{"location":"getting-started/#create-a-deepnote-account","title":"Create a Deepnote account","text":"Check your email for a sign-in link from Deepnote and click it.
Note
There are no passwords for Deepnote when signing up by email. If you explicitly log out of your Deepnote account, see our guide for how to log in.
In Deepnote, answer the introductory questions, which may depend on the type of email you used to sign up.
You should now be looking at an empty notebook that is part of the Welcome to Deepnote project within your workspace. You won\u2019t need that project for writing algorithmic essays, but you may wish to keep it, to later explore Deepnote\u2019s data science features.
For the moment, just proceed with the next steps.
"},{"location":"getting-started/#duplicate-our-project","title":"Duplicate our project","text":"We created an essay project in our Deepnote workspace, to be copied to your workspace. The project has all necessary software pre-installed.
Click Duplicate project to finish the process.
Note
Do not check the box to make your project private: that would prevent sharing your essays later with others.
After a few moments, you will see the project in your workspace, with the name Algorithmic Essays - Duplicate at the top of the screen.
Click on the three dots in the top right corner.
You should now see some notebooks in the left panel.
"},{"location":"getting-started/#copy-a-template","title":"Copy a template","text":"We provide two templates as starting points for your essay. One template is simpler, with introductory programming in mind, the other is for data structures and algorithms courses. To write an essay, copy one of the templates and edit that copy.
This creates a new notebook, with the name of the template followed by \u2018-2\u2019, and opens it.
Once you decided your essay\u2019s topic, you can rename the notebook.
"},{"location":"getting-started/#write-the-essay","title":"Write the essay","text":"Now that you have copied and renamed a template, you can start writing your essay in Deepnote.
If you\u2019re familiar with the classic Jupyter interface, we recommend you first read about the differences with Deepnote.
For a video introduction to notebooks and Deepnote, see our Deepnote guide.
For guidance on writing algorithmic essays, see our writing and coding guides.
Info
If an error occurs in a cell, click on the Show error details box in the bottom right corner of the cell to show the full stack trace.
"},{"location":"getting-started/#share-the-essay","title":"Share the essay","text":"When you are ready to share the essay with others, do the following.
For suggestions on how to ask for feedback on your shared essay, see our feedback guide
"},{"location":"getting-started/#comment-on-essays","title":"Comment on essays","text":"Once an essay has been shared with you, you can comment on it. See our guide on how to leave feedback. If you have comment permissions, do one of the following to make a comment:
After typing your comment, press the upwards blue arrow to finish.
Warning
You must be logged into your account to comment on notebooks shared with you. If you\u2019re not logged in, your comments are marked as \u2018anonymous user\u2019 and the essay\u2019s author won\u2019t see them.
"},{"location":"jn-platform-comparison/","title":"Jupyter Notebook platforms","text":"We have compared 26 Jupyter Notebook (JN) platforms against 11 criteria, to decide which platforms to support. Although we selected criteria that are relevant to our use case, writing and sharing algorithmic essays, we hope they are general enough to be of use by anyone considering the adoption of JN platforms. A comparison table is provided at the bottom of this page.
The datasciencenotebook.org website by Robert Lacok and the awesome-jupyter GitHub repository started by Markus Schanta were invaluable in locating and evaluating many of these platforms.
"},{"location":"jn-platform-comparison/#evaluation-criteria","title":"Evaluation criteria","text":"We used the following criteria to evaluate the platforms:
The following paragraphs briefly note why we have chosen each aspect, and why these features are desirable in educational settings and for writing algorithmic essays.
An important consideration for any platform is whether it is fully compatible with .ipynb files. This file type, used by many platforms, originates from when the platform was called IPython Notebook. The ability to import and export these files removes dependency on a single JN platform, allowing to write an essay in one platform and share it on another.
Being free to use, or having a free account, is a highly desirable feature of any platform. It lowers the barrier to participation for both students and educators, removes extra budget requirements, and can increase the longevity of projects.
The hosting mode (locally or in the cloud) has implications for setup requirements, UI, and collaboration. Cloud-based platforms require the least setup and typically support collaboration and commenting on cells. However, they mostly cater for data scientists in their documentation, and the UI and feature set can change without notice. Access to the underlying notebook files may be restricted, complicating code linting, and interfaces can vary, increasing the learning curve. In contrast, locally installed JN platforms tend to have a familiar and consistent interface, provide unrestricted access to files and have more balanced documentation. However, many lack simple options for collaboration and commenting, and they must be installed and configured by the user.
Any platform suitable for pedagogical practice and particularly writing algorithmic essays must have a customisable run-time environment. It should be adaptable to different course specifications, allowing the use of third-party libraries and tools. Often, the ability to install new Python packages via pip is sufficient, but some platforms go further by allowing environment customisation through a Dockerfile.
Students are often required to share their work with faculty and peers for marking, receiving feedback, and collaboration. If a platform has the option to share notebooks via links with access levels, students can grant recipients permission to read only, leave comments on, or edit the document based on their role. Links can be sent by email to specific individuals or shared with a wider audience on a forum. In some cases, work can be shared without the recipient needing an account on the same platform.
The ability for a JN platform to integrate with other platforms can be highly desirable. For instance, integration with GitHub allows one to leverage version control when developing resources, use a single repository to serve multiple platforms, and back up materials.
The user interface is often the first element of a platform a user encounters. Ease of use, familiarity and which controls are available are all important factors that can help reduce the learning curve. For users already familiar with Jupyter, it\u2019s important to consider whether a platform provides the classic JN interface or a bespoke interface. For the purpose of this comparison, we do not consider Jupyter Lab to have the classic interface.
Some platforms allow real-time collaboration among their users, to work together on documents simultaneously, and see changes instantly. Collaborating this way fosters teamwork and communication skills.
Commenting on cells is useful in many ways. Comments are located close to the relevant code or text, often contained in separate \u201cthreads\u201d where they can be edited, deleted and resolved. This allows other users to provide feedback (and educators to mark) without modifying the existing structure of the notebook.
Having access to a terminal and the underlying file system allows platform users to run custom scripts and manage auxiliary files.
Having access to the underlying notebook files in combination with access to a terminal, allows linters and formatters to be used on these files.
"},{"location":"jn-platform-comparison/#comparison-table","title":"Comparison table","text":"You may need to scroll sideways to see all columns. You can sort the table by clicking on any column header.
Some platforms may no longer exist, or may have changed their name or URL, since we compared them in January 2024.
Platform .ipynb Compatibility Free Account Hosting Customisable Run-time Share via Links GitHub Integration Interface Real-time Collaboration Commenting on Cells Terminal & File System Access Access to Notebook Files Amazon SageMaker Notebooks \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Apache Zeppelin \u2713 \u2713 Local/Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Azure Notebooks \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Carnets (iOS) \u2713 \u2713 Local \u2713 \u2717 \u2717 Classic \u2717 \u2717 \u2713 \u2713 CoCalc \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 CodeOcean \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Count \u2717 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Datalore (JetBrains) \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Deepnote \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2717 Google Colab \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Hyperquery \u2717 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 IBM Watson Studio \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Jupyter Notebook \u2713 \u2713 Local \u2713 \u2717 \u2713 Classic \u2717 \u2717 \u2713 \u2713 JupyterLab \u2713 \u2713 Local \u2713 \u2717 \u2713 Bespoke \u2713 \u2717 \u2713 \u2713 Kaggle Notebooks \u2713 \u2713 Cloud \u2717 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Mode Notebooks \u2717 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Noteable \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 nteract \u2713 \u2713 Local \u2713 \u2717 \u2713 Classic \u2717 \u2717 \u2713 \u2713 Observable \u2717 \u2713 Cloud \u2717 \u2713 \u2717 Bespoke \u2713 \u2713 \u2717 \u2717 Polynote \u2717 \u2713 Local \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Pluto.jl \u2717 \u2713 Local \u2713 \u2717 \u2717 Bespoke \u2717 \u2717 \u2713 \u2713 Query.me \u2717 \u2717 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Quarto \u2713 \u2713 Local \u2713 \u2717 \u2713 Classic \u2717 \u2717 \u2713 \u2713 Saturn Cloud \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 VS Code with Jupyter \u2713 \u2713 Local/Cloud \u2713 \u2717 \u2713 Classic/Bespoke \u2713 \u2713 \u2713 \u2713 Zepl \u2717 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717"},{"location":"library/","title":"Library","text":"The algoesup library provides support for testing, timing and linting code.
Simplified testing for Python functions
"},{"location":"library/#algoesup.test.test","title":"test","text":"test(function: Callable, test_table: list) -> None\nTest the function with the test_table. Report failed tests.
Parameters:
Name Type Description Defaultfunction Callable The function to be tested.
requiredtest_table list The list of tests. Each element of test_table is a list or tuple with: a string (the test case name); one or more values (the inputs to the function); the expected output value.
required"},{"location":"library/#timing","title":"Timing","text":"Tools for measuring and plotting run-times
"},{"location":"library/#algoesup.time.time_functions","title":"time_functions","text":"time_functions(\n functions: list[Callable],\n inputs: Callable,\n start: int,\n double: int,\n text: bool = True,\n chart: bool = False,\n value: bool = False,\n) -> None\nPrint or plot the run-times of different functions for the same inputs.
time_functions prints or plots the run-times given list of functions and an input generator. Inputs are generated based on a starting size and are doubled a specified number of times.
Parameters:
Name Type Description Defaultfunctions list[Callable] A list of functions whose run-times will be measured. Must be 1 to 6 functions.
requiredinputs Callable A function to generate inputs when given a specific size.
requiredstart int The starting size for the inputs. Must be positive.
requireddouble int The number of times to double the input size. Must be non-negative.
requiredtext bool If True, print the run-times in text format
True chart bool If True plot the run-times using a chart.
False value bool If True x-axis is labelled \u201cInput value\u201d otherwise \u201cInput size\u201d.
False Raises:
Type DescriptionAssertionError If input conditions are not satisfied.
"},{"location":"library/#algoesup.time.time_cases","title":"time_cases","text":"time_cases(\n function: Callable,\n cases: list[Callable],\n start: int,\n double: int,\n text: bool = True,\n chart: bool = False,\n) -> None\nPrint or plot the run-times of function for different input cases.
time_cases prints or plots the run-times of a single function using a list of different input generators. Inputs are generated based on a starting size and are doubled a specified number of times.
Parameters:
Name Type Description Defaultfunction Callable A function whose run-times will be measured.
requiredcases list[Callable] A list of 1 to 6 functions to generate inputs of different cases, e.g. best-, normal- and worst-case.
requiredstart int The starting size for the inputs. Must be positive.
requireddouble int The number of times to double the input size. Must be non-negative.
requiredtext bool If True, print the run-times in text format.
True chart bool If True, plot the run-times using a chart.
False Raises:
Type DescriptionAssertionError If input conditions are not satisfied.
"},{"location":"library/#algoesup.time.time_functions_int","title":"time_functions_int","text":"time_functions_int(\n functions: list[Callable],\n generator: Callable = int_value,\n start: int = 1,\n double: int = 10,\n text: bool = True,\n chart: bool = True,\n) -> None\nTime functions that take a single integer as input.
time_functions_int uses time_functions to measure and display the run-times of a given list of functions that accept a single integer input. The integer inputs are generated starting from a specified value that defaults to 1, and are doubled a specified number of times that defaults to 10.
Parameters:
Name Type Description Defaultfunctions list[Callable] A list of functions whose run-times will be measured. Each function must accept a single integer argument. Must be 1 to 6 functions.
requiredgenerator Callable A function to generate integer inputs. Defaults to int_value, which returns a tuple containing the input integer.
int_value start int The starting integer value for inputs. Defaults to 1. Must be positive.
1 double int The number of times to double the input integer value. Defaults to 10. Must be non-negative.
10 text bool If True, print the run-times in text format.
True chart bool If True, plot the run-times using a chart.
True"},{"location":"library/#linting","title":"Linting","text":"Linting tools for Jupyter Notebook environments
"},{"location":"library/#algoesup.magics.allowed","title":"allowed","text":"allowed\nActivate/deactivate the allowed linter.
When active, the linter checks each code cell that is executed for any Python constructs that are not listed in the given configuration file.
%allowed on ... activates the linter with any command options given after on%allowed on is equal to %allowed on --config m269.json%allowed off deactivates the linter%allowed shows the current status of the linter%allowed? shows this documentation and the command\u2019s optionsFor a list of possible options ..., enter !allowed -h in a code cell. Some options may not be appropriate when running allowed within a notebook.
The --config option expects m269.json, tm112.json or the name of a JSON file with your own configuration.
pytype\nActivate/deactivate the pytype linter.
When active, the linter checks each code cell that is executed for type errors.
%pytype on ... activates the linter with the command options given after on%pytype on is equal to %pytype on --disable name-error,import-error%pytype off deactivates the linter%pytype shows the current status of the linter%pytype? shows this documentation and the command\u2019s optionsFor a list of possible options ..., enter !pytype -h in a code cell. Some options may not be appropriate when running pytype within a notebook.
The --disable option expects a list of errors to ignore, without spaces. By default, %pylint ignores these errors:
ruff\nActivate/deactivate the Ruff linter.
When active, the linter checks each code cell that is executed against the selected code style rules.
%ruff on ... activates the linter with any command options given after on (see [ruff\u2019s list of rules])%ruff on is equal to %ruff on --select A,B,C90,D,E,W,F,N,PL --ignore D100,W292,F401,F821,D203,D213,D415%ruff off deactivates the linter%ruff shows the current status of the linter%ruff? shows this documentationThe command %ruff on ... will run ruff check --output-format json ... on each cell. For a list of the possible options ..., enter !ruff help check in a code cell. Some options may not be appropriate when running Ruff within a notebook.
The --select and --ignore options expect a list of rule codes, without spaces.
By default, %ruff enables the rules from flake8-builtins (A), flake8-bugbear (B), mccabe (C90), pydocstyle (D), pycodestyle (E, W), pyflakes (F), pep8-naming (N), and pylint (PL).
By default, %ruff ignores these rules:
This document provides guidance on how to produce your essay.
Warning
Although we wish to accommodate novice programmers in the future, the guide currently has data structures and algorithms students in mind.
An essay can have more than one author, although more than two is harder to manage. Deepnote and Colab make it easy to work collaboratively on a single notebook, at the same time or asynchronously, and leave comments to co-authors. You may wish to first pitch your essay idea to your peers, to recruit co-authors.
In the rest of this guide, \u2018you\u2019 and \u2018your\u2019 are both singular and plural pronouns, to refer simultaneously to a single author or multiple authors.
Tip
You may wish to keep this guide open while going through your copy of our template.
"},{"location":"writing/#problem","title":"Problem","text":"It\u2019s worth spending time on choosing an appropriate problem before putting effort into an essay about it. You may invent your own problem or select an existing one. For example, it may be a non-assessed exercise from your course, or it may relate to your hobby or work. If so, provide any information the reader needs to understand the problem. If the problem is from your work, get permission from your employer or client.
There are many websites with thousands of algorithmic problems to choose from. We have used Kattis and LeetCode in the past.
Some sites, like LeetCode, tag their problems with the data structure or algorithmic technique needed, like \u2018array\u2019 or \u2018sorting\u2019. This helps you find problems about a particular topic.
Some sites, like LeetCode, have official and user-provided solutions, but the latter may be terse (single-letter identifiers, no comments) or not fully analysed. Other sites, like the International Olympiad in Informatics, often have just solution hints or outlines. You may thus wish to write an essay that fully implements a solution outline or that improves and compares several user solutions. Either way would be useful to the user community of those sites.
It is often said that the best way to learn a topic is to have to explain it to others. You may thus wish to pick a problem on a topic you\u2019re not comfortable with, choose two existing solutions, and explain them in an essay.
If you\u2019re undecided, make a shortlist of 2\u20133 problems and ask your peers for their opinion.
"},{"location":"writing/#text","title":"Text","text":"An essay presents two or more algorithmic solutions for a computational problem, and concludes which one is better, according to some criteria. Possible criteria include:
The essay should thus have a clear narrative, going from the problem to the conclusion.
An algorithmic essay contains more text than code, and while code can and should have comments, the text carries most of the explanation. It\u2019s thus important for the text to be clear and error-free.
Essays can be written in any style: it\u2019s a personal choice. For example, you can use \u2018we\u2019, \u2018I\u2019 or an impersonal form.
Tip
Strunk and White\u2019s The Elements of Style is a classic. The examples are dated but the advice is good.
Deepnote
Notebooks can have rich-text cells (headings, paragraph, bullet item, etc.) that, contrary to the Markdown cells, are spell-checked as you write the text and support keyboard shortcuts, like Ctrl + B to put the selected text in bold. Unless you want to keep your essays in Deepnote, we do not recommend using rich-text cells, as their formatting is lost when downloading the notebook to your computer.
"},{"location":"writing/#structure","title":"Structure","text":"An essay starts with a title that states the problem or the algorithmic technique to be used. Next, put your name(s) and the current date, which should be updated whenever you edit the essay.
Next, without any heading, comes the introduction. It should state what the essay is about. Normally an essay\u2019s aim is to solve a particular problem, but it may also illustrate a general technique, like space-time trade-offs or recursion, or highlight an issue, like the difference between complexity analysis and run-time performance.
The introduction should also state what you assume the reader to know, as no essay can explain everything from first principles. For example, tell the reader that they must know about binary trees to understand your essay.
Following the introduction, use section headings to structure your essay, for example:
The algorithms and implementations sections may have subsections, one per algorithm.
An alternative structure implements each approach before evaluating all of them:
If the problem description is a single paragraph, you may include it in the introduction, rather than having a separate section. If you didn\u2019t invent the problem, indicate its source, e.g. by providing a link to a website or by writing something like \u201cThis is problem 4.5 in [book title] by [author].\u201d
"},{"location":"writing/#algorithms","title":"Algorithms","text":"You should choose at least two sufficiently different algorithms that solve the problem, and describe each one succinctly, preferably before implementing it, to make the code easier to understand for the reader.
We recommend to not describe algorithms that are only slight variants of each other, as this is usually of little interest, and to only include two algorithms in your first draft.
If you\u2019re using solutions by others, e.g. by LeetCode users, acknowledge the original author and provide a link to their solution. If you have modified their solutions, state what you have changed and explain why.
You should include worst-case complexity analyses of the various solutions you propose, as this helps discard the inefficient ones that may not be worth implementing.
"},{"location":"writing/#code","title":"Code","text":"See our coding guide.
"},{"location":"writing/#final-check","title":"Final check","text":"Whether it\u2019s your essay\u2019s first draft or final version, before you share it with others, you should restart the kernel and run all cells, so that you have a \u2018clean\u2019 version. Then, after a break, read your essay with \u2018fresh eyes\u2019 from start to end and fix any typos or missing explanations you find.
Look at the table of contents of your notebook and check that your section headings are at the right level.
Deepnote
The table of contents is on the left sidebar.
Colab
To see the table of contents, click the bullet list icon in the left sidebar.
Finally, let others comment on your essay and help you produce a better version. See our feedback guide for details.
"},{"location":"essays/example-1-to-n/","title":"Sum of 1 to n","text":"This short notebook provides a very simple example of an algorithmic essay and shows the support that our library provides.
The problem to be solved is to compute the sum of the integers, 1, 2, ..., n, for some given n. Two solutions will be presented, both only using basic Python.
The first thing to do is to import the necessary functions from the algorithmic essays support library. The functions will be explained later, when they're used.
In\u00a0[1]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff In\u00a0[2]: Copied!
# import functions to test the code and to measure the execution time\nfrom algoesup import test, time_functions_int\n# import functions to test the code and to measure the execution time from algoesup import test, time_functions_int
The library also includes two commands to turn on the tools that will check the code as it's executed. There won't be any messages in this notebook because the code passes all checks.
In\u00a0[3]: Copied!%load_ext algoesup.magics\n# check the code for style violations\n%ruff on\n# check that only the subset of Python taught in our introductory course TM112 is used\n%allowed on --config tm112.json\n%load_ext algoesup.magics # check the code for style violations %ruff on # check that only the subset of Python taught in our introductory course TM112 is used %allowed on --config tm112.json
ruff was activated\nallowed was activated\nIn\u00a0[4]: Copied!
tests = [\n # case n, sum\n [\"no integers\", -1, 0],\n [\"one integer\", 1, 1],\n [\"n is even\", 4, 10], # 1 + 2 + 3 + 4 = 10\n [\"n is odd\", 7, 28], # 1 + 2 + 3 + 4 + 5 + 6 + 7 = 28\n]\ntests = [ # case n, sum [\"no integers\", -1, 0], [\"one integer\", 1, 1], [\"n is even\", 4, 10], # 1 + 2 + 3 + 4 = 10 [\"n is odd\", 7, 28], # 1 + 2 + 3 + 4 + 5 + 6 + 7 = 28 ] In\u00a0[5]: Copied!
def sum_with_loop(n):\n \"\"\"Return 1 + 2 + ... + n, using a loop.\"\"\"\n total = 0\n for number in range(1, n + 1):\n total = total + number\n return total\ndef sum_with_loop(n): \"\"\"Return 1 + 2 + ... + n, using a loop.\"\"\" total = 0 for number in range(1, n + 1): total = total + number return total
The next step is to check the code with the imported test function, which takes two arguments: the function to be tested and a test table. Every test case in the test table is checked and if the actual output isn't the expected output, the test is reported as having failed.
test(sum_with_loop, tests)\ntest(sum_with_loop, tests)
Testing sum_with_loop...\nTests finished: 4 passed, 0 failed.\n
Algorithm 1 passes all tests. Since the algorithm does exactly what the problem asks for, the only test that could fail is for n < 1. However, in that case the loop is skipped and the returned total is zero, as desired.
In\u00a0[7]: Copied!def sum_with_formula(n):\n \"\"\"Return 1 + 2 + ... + n, using a formula.\"\"\"\n return n * (n + 1) // 2\ndef sum_with_formula(n): \"\"\"Return 1 + 2 + ... + n, using a formula.\"\"\" return n * (n + 1) // 2
This function is solving the same problem as the previous one, so it must be tested with the exact same tests.
In\u00a0[8]: Copied!test(sum_with_formula, tests)\ntest(sum_with_formula, tests)
Testing sum_with_formula...\nTests finished: 4 passed, 0 failed.\n
The code passes the tests, and yet the algorithm is wrong! The formula is only meant for n \u2265 1. It just happens that if n = 0 or n = -1 then n \u00b7 (n+1) / 2 = 0, as desired, but for n < -1 the result is non-zero. An additional test helps confirm this.
In\u00a0[9]: Copied!tests.append([\"n < -1\", -5, 0]) # testing with n = -5\n\ntest(sum_with_formula, tests)\ntests.append([\"n < -1\", -5, 0]) # testing with n = -5 test(sum_with_formula, tests)
Testing sum_with_formula...\nn < -1 FAILED: 10 instead of 0\nTests finished: 4 passed, 1 failed.\n
The result is -5 \u00b7 (\u20135 + 1) / 2 = -5 \u00b7 -4 / 2 = 10 instead of zero. The algorithm must be modified.
Algorithm 2 (corrected): If n < 1, return 0, otherwise return n \u00b7 (n+1) / 2.
In\u00a0[10]: Copied!def sum_with_formula(n):\n \"\"\"Return 1 + 2 + ... + n, using a formula.\"\"\"\n if n < 1:\n return 0\n else:\n return n * (n + 1) // 2\n\ntest(sum_with_formula, tests)\ndef sum_with_formula(n): \"\"\"Return 1 + 2 + ... + n, using a formula.\"\"\" if n < 1: return 0 else: return n * (n + 1) // 2 test(sum_with_formula, tests)
Testing sum_with_formula...\nTests finished: 5 passed, 0 failed.\n
Now the additional test also passes.
As a new test was added, the first algorithm must be tested again.
In\u00a0[11]: Copied!test(sum_with_loop, tests)\ntest(sum_with_loop, tests)
Testing sum_with_loop...\nTests finished: 5 passed, 0 failed.\nIn\u00a0[12]: Copied!
time_functions_int([sum_with_loop, sum_with_formula])\ntime_functions_int([sum_with_loop, sum_with_formula])
Inputs generated by int_value\n\nInput value sum_with_loop sum_with_formul \n 1 152.7 88.2 ns\n 2 175.8 88.5 ns\n 4 207.0 88.6 ns\n 8 276.6 88.3 ns\n 16 401.7 95.0 ns\n 32 705.5 99.5 ns\n 64 1388.1 99.6 ns\n 128 2650.9 99.7 ns\n 256 5189.3 103.1 ns\n 512 11156.8 103.0 ns\n 1024 23184.4 104.4 ns
Computing the sum with the formula always takes about the same time, around 90 to 100 nanoseconds (that's what the 'ns' means). However, the run-times for the sum with the loop grow as n gets larger. If the value of n doubles, the number of iterations also doubles, so the run-time also roughly doubles, as can be seen above the chart. As n increases, the iterative sum gets slower and slower. At n = 1024, using a loop is about 200 times slower than using the formula!
"},{"location":"essays/example-1-to-n/#sum-of-1-to-n","title":"Sum of 1 to n\u00b6","text":"Michel Wermelinger, 22 January 2024, last updated 16 March 2024
"},{"location":"essays/example-1-to-n/#tests","title":"Tests\u00b6","text":"Before thinking of a solution, it's best to write down some tests, as they help our understanding of the problem. Each test is the input integer n and the corresponding expected integer output 1 + 2 + ... + n.
The tests should include edge cases: inputs that are extreme values or that lead to extreme outputs. For this problem, edge cases are when there are no integers to add up (n < 1) or when there's only one (n = 1).
Tests should also include normal cases. When the input is an integer, tests typically include odd and even values.
The test function that was imported in the previous cell expects the tests to be written as a table, e.g. as a list of lists. The table must have one row per test case. Each row has a column with a string describing the case, one column per input, and a final column with the expected output.
The next step is to think of possible algorithms that solve the problem.
"},{"location":"essays/example-1-to-n/#using-a-loop","title":"Using a loop\u00b6","text":"The probably most obvious algorithm is to explicitly calculate the sum, by iterating over the integers from 1 to n.
Algorithm 1: Set the total to zero. For each value from 1 to n, add the value to the total. Return the total.
The algorithm is implemented as follows.
"},{"location":"essays/example-1-to-n/#using-a-formula","title":"Using a formula\u00b6","text":"It's possible to compute the sum directly, using a well-known formula, taught in many introductory math courses:
1 + 2 + 3 + ... + (n - 2) + (n - 1) + n = (1 + n) + (2 + n - 1) + (3 + n - 2) + ... = (n + 1) \u00b7 n / 2.
The formula is based on 'pairing up' the first with the last number, the second with the next to last, and so on. Each pair adds up to n + 1, and the number of pairs is half of n. The algorithm is simply the formula:
Algorithm 2: Return n \u00b7 (n+1) / 2.
"},{"location":"essays/example-1-to-n/#performance","title":"Performance\u00b6","text":"The final, optional, step is to compare the performance of both solutions to see which is fastest. For this problem, the second algorithm is expected to be faster that the first one, as it computes the sum directly, without iterating over n integers.
The time_functions_int function, which was imported in the first cell, takes a list of functions that have a single integer n as input, and measures their run-times for n = 1, 2, 4, 8, ..., 1024. Doubling the input allows to see any trends in how run-times grow with just eleven executions of the two functions. Running the functions with n = 1, 2, 3, 4, 5, ..., 1024 would take much longer and not produce any additional insight.
This essay presented two solutions to a simple problem: computing the sum 1 + ... + n, for any integer n. The sum should be zero if n < 1.
The first solution computes the sum iteratively, while the second computes it directly, with a formula. The second is always faster, even for n = 1. Moreover, as n increases, the first approach becomes slower whereas the second always takes about the same time.
This essay illustrates the need for thinking about different algorithms for the same problem, as one approach may be much more efficient than others.
The essay also showed that passing all tests doesn't mean that the code is correct. As the various algorithms are developed, new tests may have to be added.
"},{"location":"essays/example-jewels/","title":"Jewels and Stones","text":"In this example algorithmic essay I will tackle LeetCode problem Jewels and Stones. The inputs are two strings jewels and stones, where each character represents a type of stone, e.g. A for amethyst, D for diamond, b for basalt and ? for an unknown stone. The jewels string contains the characters that represent jewels, without repetition. The desired output is the number of stones that are jewels. For example, if jewels is \"AD\" and stones is \"b?AbDAb\" then the output is 3 because three of the stones are jewels (two amethysts and one diamond). To be clear, which stones and jewels the characters represent doesn't really matter: the output is simply how many characters of the second string occur in the first string.
This essay will illustrate a space-time trade-off: by using an additional data structure, we get a faster algorithm. I assume you're familiar with sets, bags (multisets) and basic complexity analysis. This essay uses Big-Theta notation \u0398(...), but if you're not familiar with it, you can read it as Big-Oh notation O(...) for the purposes of the analyses done below. Sorting, binary search, and log-linear and logarithmic complexities are mentioned in Section 2.3, but you can skip it, as it won't affect the understanding of the rest of the essay.
Before starting to solve the problem, I import the necessary functions from algoesup, the algorithmic essays support library, and turn on the tools that will check my code for style and type violations (with Ruff and pytype), and for constructs I didn't teach (with allowed).
import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff pytype\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff pytype In\u00a0[2]: Copied!
from algoesup import test, time_cases, time_functions\nfrom algoesup import test, time_cases, time_functions In\u00a0[3]: Copied!
%load_ext algoesup.magics\n%ruff on\n%pytype on\n%allowed on\n%load_ext algoesup.magics %ruff on %pytype on %allowed on
ruff was activated\npytype was activated\nallowed was activated\nIn\u00a0[4]: Copied!
# don't allow code formatters to change this table\n# fmt: off\ntests = [\n # case jewels stones output\n (\"no jewels\", \"\", \"abc\", 0),\n (\"no stones\", \"DA\", \"\", 0),\n (\"both empty\", \"\", \"\", 0),\n (\"none is a jewel\", \"DA\", \"dada?\", 0),\n (\"equal strings\", \"DA\", \"DA\", 2),\n (\"all same jewel\", \"DA\", \"AAAA\", 4),\n (\"some jewels missing\", \"DARJ\", \"RRD\", 3),\n (\"some not jewels\", \"RAD\", \"bRADAb\", 4),\n]\n# allow code formatters to change the following cells\n# fmt: on\n# don't allow code formatters to change this table # fmt: off tests = [ # case jewels stones output (\"no jewels\", \"\", \"abc\", 0), (\"no stones\", \"DA\", \"\", 0), (\"both empty\", \"\", \"\", 0), (\"none is a jewel\", \"DA\", \"dada?\", 0), (\"equal strings\", \"DA\", \"DA\", 2), (\"all same jewel\", \"DA\", \"AAAA\", 4), (\"some jewels missing\", \"DARJ\", \"RRD\", 3), (\"some not jewels\", \"RAD\", \"bRADAb\", 4), ] # allow code formatters to change the following cells # fmt: on In\u00a0[5]: Copied!
def count_in_string(jewels: str, stones: str) -> int:\n \"\"\"Return the number of characters in `stones` that are in `jewels`.\n\n Use Algorithm 2: for each stone, check if it's a jewel.\n Complexity: best \u0398(len(stones)); worst \u0398(len(stones) * len(jewels))\n \"\"\"\n counter = 0\n for stone in stones:\n if stone in jewels:\n counter = counter + 1\n return counter\n\n\n# test(function, test_table) runs `function` on each test in `test_table`\n# and prints the tests that fail (actual output isn't the expected output).\ntest(count_in_string, tests)\ndef count_in_string(jewels: str, stones: str) -> int: \"\"\"Return the number of characters in `stones` that are in `jewels`. Use Algorithm 2: for each stone, check if it's a jewel. Complexity: best \u0398(len(stones)); worst \u0398(len(stones) * len(jewels)) \"\"\" counter = 0 for stone in stones: if stone in jewels: counter = counter + 1 return counter # test(function, test_table) runs `function` on each test in `test_table` # and prints the tests that fail (actual output isn't the expected output). test(count_in_string, tests)
Testing count_in_string...\nTests finished: 8 passed, 0 failed.\n
The implementation of Algorithm 2 passes all tests. Next, Algorithm 3 can be implemented with Python's Counter class.
from collections import Counter\n\n\ndef count_in_bag(jewels: str, stones: str) -> int:\n \"\"\"Return the number of characters in `stones` that are in `jewels`.\n\n Use Algorithm 3: put stones in a bag; add the frequencies of those that are jewels.\n Complexity: \u0398(len(stones) + len(jewels))\n \"\"\"\n bag = Counter(stones)\n counter = 0\n for jewel in jewels:\n counter = counter + bag[jewel]\n return counter\n\n\ntest(count_in_bag, tests)\nfrom collections import Counter def count_in_bag(jewels: str, stones: str) -> int: \"\"\"Return the number of characters in `stones` that are in `jewels`. Use Algorithm 3: put stones in a bag; add the frequencies of those that are jewels. Complexity: \u0398(len(stones) + len(jewels)) \"\"\" bag = Counter(stones) counter = 0 for jewel in jewels: counter = counter + bag[jewel] return counter test(count_in_bag, tests)
Testing count_in_bag...\nTests finished: 8 passed, 0 failed.\n
Finally, Algorithm 4 can be implemented with Python's built-in set type.
def count_in_set(jewels: str, stones: str) -> int:\n \"\"\"Return the number of characters in `stones` that are in `jewels`.\n\n Use Algorithm 4: put jewels in a set; count the stones that are in the set.\n Complexity: \u0398(len(jewels) + len(stones))\n \"\"\"\n jewel_set = set(jewels)\n counter = 0\n for stone in stones:\n if stone in jewel_set:\n counter = counter + 1\n return counter\n\n\ntest(count_in_set, tests)\ndef count_in_set(jewels: str, stones: str) -> int: \"\"\"Return the number of characters in `stones` that are in `jewels`. Use Algorithm 4: put jewels in a set; count the stones that are in the set. Complexity: \u0398(len(jewels) + len(stones)) \"\"\" jewel_set = set(jewels) counter = 0 for stone in stones: if stone in jewel_set: counter = counter + 1 return counter test(count_in_set, tests)
Testing count_in_set...\nTests finished: 8 passed, 0 failed.\nIn\u00a0[8]: Copied!
def best_case(size: int) -> tuple[str, str]:\n \"\"\"Return a best-case input (pair of strings) of the given size.\n\n Output: (jewels, stones) with\n - len(jewels) + len(stones) == size, with each string half the size\n - jewels has no duplicate characters\n - all stones are jewels[0]\n \"\"\"\n j = size // 2\n s = size - j\n # create a string with j different characters (Unicode 32 onwards)\n jewels = \"\"\n for code in range(32, 32 + j):\n jewels = jewels + chr(code)\n # create a string with s spaces (Unicode 32), the first character in jewels\n stones = \" \" * s\n return (jewels, stones)\ndef best_case(size: int) -> tuple[str, str]: \"\"\"Return a best-case input (pair of strings) of the given size. Output: (jewels, stones) with - len(jewels) + len(stones) == size, with each string half the size - jewels has no duplicate characters - all stones are jewels[0] \"\"\" j = size // 2 s = size - j # create a string with j different characters (Unicode 32 onwards) jewels = \"\" for code in range(32, 32 + j): jewels = jewels + chr(code) # create a string with s spaces (Unicode 32), the first character in jewels stones = \" \" * s return (jewels, stones)
allowed found issues:
Note that the allowed tool reports that I haven't taught my students the chr function. That's why I explained it before presenting the code.
Moving on, I write some tests, to check that best_case is generating the right strings.
# fmt: off\ntest(best_case, [\n # case, size, (jewels, stones)\n (\"empty strings\", 0, (\"\", \"\")),\n (\"no jewels\", 1, (\"\", \" \")),\n (\"odd size\", 5, (' !', \" \")),\n])\n# fmt: on\n # fmt: off test(best_case, [ # case, size, (jewels, stones) (\"empty strings\", 0, (\"\", \"\")), (\"no jewels\", 1, (\"\", \" \")), (\"odd size\", 5, (' !', \" \")), ]) # fmt: on Testing best_case...\nTests finished: 3 passed, 0 failed.\n
To generate a worst case, I have two options: no stone is a jewel or all stones are the last jewel (Unicode 31 + j). I choose the first one. (Spoiler alert: I made the wrong choice. Can you see why?)
In\u00a0[10]: Copied!def worst_case(size: int) -> tuple[str, str]:\n \"\"\"Return a worst-case input (pair of strings) of the given size.\n\n Output: (jewels, stones) with\n - len(jewels) + len(stones) == size, with each string half the size\n - jewels has no duplicate characters\n - no stone is a jewel\n \"\"\"\n j = size // 2\n s = size - j\n # create a string with j different characters (Unicode 32 onwards)\n jewels = \"\"\n for code in range(32, 32 + j):\n jewels = jewels + chr(code) # allowed\n # create a string with s different characters (Unicode 32+j onwards)\n stones = \"\"\n for code in range(32 + j, 32 + j + s):\n stones = stones + chr(code) # allowed\n return (jewels, stones)\n\n\n# fmt: off\ntest(worst_case, [\n # case, size, (jewels, stones)\n (\"empty strings\", 0, (\"\", \"\")),\n (\"no jewels\", 1, (\"\", \" \")),\n (\"odd size\", 11, (' !\"#$', \"%&'()*\")), # 5 jewels, 6 stones\n])\n# fmt: on\n def worst_case(size: int) -> tuple[str, str]: \"\"\"Return a worst-case input (pair of strings) of the given size. Output: (jewels, stones) with - len(jewels) + len(stones) == size, with each string half the size - jewels has no duplicate characters - no stone is a jewel \"\"\" j = size // 2 s = size - j # create a string with j different characters (Unicode 32 onwards) jewels = \"\" for code in range(32, 32 + j): jewels = jewels + chr(code) # allowed # create a string with s different characters (Unicode 32+j onwards) stones = \"\" for code in range(32 + j, 32 + j + s): stones = stones + chr(code) # allowed return (jewels, stones) # fmt: off test(worst_case, [ # case, size, (jewels, stones) (\"empty strings\", 0, (\"\", \"\")), (\"no jewels\", 1, (\"\", \" \")), (\"odd size\", 11, (' !\"#$', \"%&'()*\")), # 5 jewels, 6 stones ]) # fmt: on Testing worst_case...\nTests finished: 3 passed, 0 failed.\n
The # allowed comment in lines 14 and 18 tells the tool that chr() is allowed, because it was explained, and hence should not be reported.
Finally I generate random typical cases in which not all stones are jewels and not all jewels occur in the stones.
In\u00a0[11]: Copied!import random\n\n\ndef normal_case(size: int) -> tuple[str, str]:\n \"\"\"Return a typical input (pair of strings) of the given size.\n\n Output: (jewels, stones) with\n - len(jewels) + len(stones) == size, with each string half the size\n - jewels has no duplicate characters\n - stones has some jewels and some non-jewels, if len(jewels) > 1\n - not all jewels occur in stones, if len(jewels) > 1\n \"\"\"\n j = size // 2\n s = size - j\n # create a string with j different characters (Unicode 32 onwards)\n jewels = \"\"\n for code in range(32, 32 + j):\n jewels = jewels + chr(code) # allowed\n # create a string with s random characters from Unicode 33 to 33 + 2j\n stones = \"\"\n for _ in range(s):\n stones = stones + chr(random.randint(33, 33 + 2 * j)) # allowed\n return (jewels, stones)\n\n\n# Can't test with a test table, because the output is random.\n(jewels, stones) = normal_case(20)\ncounter = count_in_string(jewels, stones)\nprint(\"Some stones are jewels:\", counter > 0)\nprint(\"Some stones aren't jewels:\", counter < len(stones))\nimport random def normal_case(size: int) -> tuple[str, str]: \"\"\"Return a typical input (pair of strings) of the given size. Output: (jewels, stones) with - len(jewels) + len(stones) == size, with each string half the size - jewels has no duplicate characters - stones has some jewels and some non-jewels, if len(jewels) > 1 - not all jewels occur in stones, if len(jewels) > 1 \"\"\" j = size // 2 s = size - j # create a string with j different characters (Unicode 32 onwards) jewels = \"\" for code in range(32, 32 + j): jewels = jewels + chr(code) # allowed # create a string with s random characters from Unicode 33 to 33 + 2j stones = \"\" for _ in range(s): stones = stones + chr(random.randint(33, 33 + 2 * j)) # allowed return (jewels, stones) # Can't test with a test table, because the output is random. (jewels, stones) = normal_case(20) counter = count_in_string(jewels, stones) print(\"Some stones are jewels:\", counter > 0) print(\"Some stones aren't jewels:\", counter < len(stones))
Some stones are jewels: True\nSome stones aren't jewels: True\n
The loop variable's name is just an underscore (line 21) to avoid a warning that the loop variable isn't used in the loop's body.
In\u00a0[12]: Copied!cases = [best_case, normal_case, worst_case]\ntime_cases(count_in_string, cases, start=10, double=4)\ncases = [best_case, normal_case, worst_case] time_cases(count_in_string, cases, start=10, double=4)
Run-times for count_in_string\n\nInput size best_case normal_case worst_case \n 10 202.6 198.2 155.0 ns\n 20 337.8 324.3 299.8 ns\n 40 596.3 550.1 425.1 ns\n 80 1088.7 1043.6 796.5 ns\n 160 2071.6 2272.3 1558.1 ns
The results are baffling: the worst case is the fastest!
The linear search is done with the in operator, which is much faster than implementing the search in Python. Due to the very small input sizes, with at most 80 jewels and 80 stones, it doesn't really matter whether the search stops at the first jewel or goes through all the jewels.
Since the search takes about the same time in the best and worst cases, what makes the difference to the overall run-time is how often the counter is updated. In the best case (all stones are the first jewel) the counter is always incremented, whereas in the worst case (no stone is a jewel) the counter is never incremented. Hence, the worst case is faster than the best case.
The real issue is that I'm not generating worst cases. I'm not constructing inputs that make Algorithm 2 do the most work. A worst case should make the linear search go through all the jewels and increment the counter for each one. The worst case is actually when all stones are the last jewel.
I should go back, modify the worst_case function so that stones = chr(31 + j) * s, and run again the previous cell. Instead, I will run count_in_string on larger inputs. That will avoid the search taking about the same time whether a stone is the first jewel or not a jewel. This time I also ask for a graphical output.
time_cases(count_in_string, cases, start=1000, double=4, chart=True)\ntime_cases(count_in_string, cases, start=1000, double=4, chart=True)
Run-times for count_in_string\n\nInput size best_case normal_case worst_case \n 1000 14.6 34.7 35.4 \u00b5s\n 2000 30.3 107.4 116.4 \u00b5s\n 4000 61.4 332.3 386.1 \u00b5s\n 8000 123.6 1112.0 1359.6 \u00b5s\n 16000 248.5 3979.9 5061.5 \u00b5s
The best-case run-times double as the input size doubles, confirming the linear complexity. The worst-case run-times about quadruple as the input size doubles, confirming the quadratic complexity.
In\u00a0[14]: Copied!algorithms = [count_in_string, count_in_set, count_in_bag]\ntime_functions(algorithms, normal_case, 1000, 4, chart=True)\nalgorithms = [count_in_string, count_in_set, count_in_bag] time_functions(algorithms, normal_case, 1000, 4, chart=True)
Inputs generated by normal_case\n\nInput size count_in_string count_in_set count_in_bag \n 1000 36.6 36.6 67.6 \u00b5s\n 2000 111.4 89.2 147.5 \u00b5s\n 4000 339.8 189.6 309.0 \u00b5s\n 8000 1124.1 411.1 633.5 \u00b5s\n 16000 4014.9 851.0 1297.3 \u00b5s
As expected, using a set or bag pays off as the input size increases: as there are more jewels and stones, the linear search takes longer, but looking up a stone in a set of jewels or a jewel in a bag of stones takes constant time. However, for small inputs, a linear search is fast and hence the extra time to create the additional data structure doesn't pay off.
Using a set of jewels is about twice as fast as using a bag of stones, maybe because set is built-in and implemented in C, a very fast language, whereas Counter is part of the standard library implemented in Python, which is much slower. This example shows that algorithms with the same complexity can perform differently in practice, because the complexity tells us how the run-times grow, but not how fast or slow they are.
Michel Wermelinger, 23 January 2024, last updated 13 March 2024
"},{"location":"essays/example-jewels/#1-tests","title":"1 Tests\u00b6","text":"Before thinking of any solution, I write down some tests. Each test is two input strings and the expected integer output. I need to think of edge cases: inputs that are extreme values or that lead to extreme outputs.
For this problem, one edge case is that none of the stones is a jewel, which can happen in several ways: there are no stones; there are no jewels; there are stones and jewels but no character in stones occurs in jewels. Note that the problem statement doesn't prevent the strings to be empty, so we must assume they may be.
Another edge case is that all stones are jewels, which again can happen in several ways: the two input strings are the same; all stones are the same jewel; each stone is a jewel but not all jewels are among the stones.
Besides the edge cases I must also consider normal cases, where the stones include jewels and non-jewels and where the stones don't appear in the same order as the jewels.
I write the tests succinctly as a table, with one row per test, and one column with a string describing the test, one column per input, and a final column with the expected output. Later, I will use a function from algoesup to run all the tests and report those where the actual outputs differ from the expected ones.
Next I think of possible algorithms and their complexity, to decide which ones are worth implementing.
"},{"location":"essays/example-jewels/#21-without-additional-data","title":"2.1 Without additional data\u00b6","text":"I first attempt to solve the problem directly on the input strings. One approach that comes to mind is to count how often each jewel occurs among the stones.
Algorithm 1: Set a counter to zero. For each jewel, iterate over the stones. If a stone is the same as the current jewel, increment the counter. After going through all jewels, return the counter.
If j is the number of jewels and s the number of stones, then this algorithm always has complexity j \u00d7 \u0398(s) = \u0398(j \u00d7 s) because it does at most two constant-time operations, checking equality and incrementing the counter, for each jewel and stone.
The first approach searches each jewel among the stones. The symmetric approach is to search each stone among the jewels:
Algorithm 2: Set a counter to zero. For each stone, do a linear search for it among the jewels. If it is found, increment the counter. After going through all stones, return the counter.
In the best case, each stone is the first jewel, and the search takes constant time. The best-case complexity is s \u00d7 \u0398(1) = \u0398(s). In the worst case, the search goes through all the jewels, because the stone isn't a jewel or is the last jewel. The worst-case complexity is s \u00d7 \u0398(j) = \u0398(s \u00d7 j).
"},{"location":"essays/example-jewels/#22-with-additional-data","title":"2.2 With additional data\u00b6","text":"My next attempts consider pre-processing the inputs to make the searches faster.
Algorithm 1 goes through the stones j times, each time counting how often a jewel occurs. It's more efficient to go through the stones only once, counting how often each stone occurs, and then add the counts of those that are jewels. We need to know the frequency of each stone and the natural data type for that is the bag (or multiset).
Algorithm 3: Put all stones in a bag. Initialise a counter to zero. For each jewel, add to the counter the frequency of that jewel in the bag. Return the value of the counter.
If the bag type is implemented efficiently, both adding an item and obtaining its frequency take constant time. The complexity of Algorithm 3 is thus s \u00d7 \u0398(1) + j \u00d7 \u0398(1) = \u0398(s + j).
Algorithm 2 checks if each stone is a jewel. Is there an abstract data type (ADT) that provides such an operation? Yes, the set ADT allows checking if an item is a member of a set, which leads to...
Algorithm 4: Put all jewels in a set. Initialise a counter to zero. For each stone, if it is a member of the set, increment the counter. Return the value of the counter.
If the set ADT is implemented efficiently, both adding an item and checking membership take constant time. The complexity of Algorithm 4 is thus j \u00d7 \u0398(1) + s \u00d7 \u0398(1) = \u0398(j + s).
"},{"location":"essays/example-jewels/#23-with-sorting","title":"2.3 With sorting\u00b6","text":"The order of jewels and stones in the input strings doesn't affect the output (the number of stones that are jewels). I can thus sort the jewels, the stones, or both, to use logarithmic binary search instead of linear search.
However, sorting takes linear time in the best case and log-linear or quadratic time in the worst case. I already have algorithms that are linear in the total size of the input, so sorting wouldn't be more efficient. I therefore do not further pursue this approach.
"},{"location":"essays/example-jewels/#24-summary","title":"2.4 Summary\u00b6","text":"Algorithms 1 and 2 don't use additional memory, but have complexity \u0398(j \u00d7 s), while Algorithms 3 and 4 have better complexity \u0398(j + s), but have the run-time and memory overhead of an additional data structure. In practice, Algorithms 3 and 4 might be slower than Algorithms 1 and 2, so it's best to implement all of them.
However, Algorithm 1 always takes \u0398(j \u00d7 s) whereas Algorithm 2 only does so in the worst case. I therefore won't implement Algorithm 1.
Algorithm 3 creates a set with j jewels, whereas Algorithm 4 creates a bag with s stones. Typically, we expect inputs to have more stones than jewels (j < s), so Algorithm 3 is likely to be faster. Nevertheless, I'll implement Algorithm 4 too, for comparison.
"},{"location":"essays/example-jewels/#3-code","title":"3 Code\u00b6","text":"The next function implements Algorithm 2, using Python's in operator to do the linear search.
Finally, I will measure the run-times of the above functions with the algoesup library. The library expects us to define functions that construct inputs for a given total size.
This problem has two inputs, so I must decide how to divide the total size among both strings. I'll divide it equally: s = j. (For odd n, s = j + 1.) In that way, the expected run-times will be linear or quadratic in s: \u0398(s + j) = \u0398(2s) = \u0398(s) or \u0398(s \u00d7 j) = \u0398(s\u00b2). This makes it easy to check them empirically.
I write a function to generate a best-case input: each stone is the first jewel. To generate the input strings, I use Python's built-in chr function to obtain a character, given its Unicode number. The first 31 characters are mostly unprintable control characters, so I start at code 32 (space character).
Algorithms 3 and 4 always have the same complexity, but not so for Algorithm 2. I can measure its run-times on best, typical and worst cases, using the library's time_cases. I start with an input size of 10 and double it four times to 20, 40, 80 and 160.
The library provides time_functions to measure the run-times of up to 6 functions on the same inputs. I run the three implemented algorithms on typical inputs, with the same sizes as before.
This essay explored a simple problem: how many of the characters in a string occur in another string? There are at least 7 algorithms: 2 don't require any additional data structure, 2 use a set or a bag to achieve constant-time searches, and 3 other sort one or both inputs. Three of the first four algorithms were implemented in Python and their run-times measured. Using a set is the best option: the complexity is the lowest possible (linear in the total size of the inputs), and the run-times are better than using a bag.
"},{"location":"essays/example-two-sum-2/","title":"Two Sum (two solutions)","text":"This simple algorithmic essay aims to solve the classic Two Sum problem from LeetCode.
Readers should have an intermediate understanding of Python to understand this essay.
In\u00a0[1]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff In\u00a0[2]: Copied!
from algoesup import test, time_functions\nfrom algoesup import test, time_functions In\u00a0[3]: Copied!
%load_ext algoesup.magics\n%ruff on\n%allowed on\n%load_ext algoesup.magics %ruff on %allowed on
ruff was activated\nallowed was activated\nIn\u00a0[4]: Copied!
two_sum_tests = [\n # [\"description\", nums, target, expected_output],\n [\"minimum size for nums\", [1, 2], 3, (0, 1)],\n [\"non-adjacent indices\", [1, 4, 9, 7], 8, (0, 3)],\n [\"first two elements\", [5, 7, 1, 2, 8], 12, (0, 1)],\n [\"last two elements\", [1, 3, 5, 7, 8], 15, (3, 4)],\n [\"repeated elements\", [6, 2, 3, 2], 4, (1, 3)],\n [\"max and min range\", [-109, 109, 0], 0, (0, 1)],\n [\"lowest target value\", [-50, 1, -59], -109, (0, 2)],\n [\"highest target value\", [50, 1, 59], 109, (0, 2)],\n]\ntwo_sum_tests = [ # [\"description\", nums, target, expected_output], [\"minimum size for nums\", [1, 2], 3, (0, 1)], [\"non-adjacent indices\", [1, 4, 9, 7], 8, (0, 3)], [\"first two elements\", [5, 7, 1, 2, 8], 12, (0, 1)], [\"last two elements\", [1, 3, 5, 7, 8], 15, (3, 4)], [\"repeated elements\", [6, 2, 3, 2], 4, (1, 3)], [\"max and min range\", [-109, 109, 0], 0, (0, 1)], [\"lowest target value\", [-50, 1, -59], -109, (0, 2)], [\"highest target value\", [50, 1, 59], 109, (0, 2)], ] In\u00a0[5]: Copied!
def two_sum_bf(nums, target):\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\"\"\"\n for index_1 in range(len(nums)):\n for index_2 in range(len(nums)):\n if index_1 != index_2 and nums[index_1] + nums[index_2] == target:\n return index_1, index_2\n\ntest(two_sum_bf, two_sum_tests)\ndef two_sum_bf(nums, target): \"\"\"Given a list of integers return the indices of the pair that sums to target.\"\"\" for index_1 in range(len(nums)): for index_2 in range(len(nums)): if index_1 != index_2 and nums[index_1] + nums[index_2] == target: return index_1, index_2 test(two_sum_bf, two_sum_tests)
Testing two_sum_bf...\nTests finished: 8 passed, 0 failed.\n
Next up is the Mapping algorithm implemented using Python's dict.
def two_sum_map(nums, target):\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\"\"\"\n differences = {}\n for index in range(len(nums)):\n difference = target - nums[index]\n if nums[index] in differences:\n return differences[nums[index]], index\n differences[difference] = index\n\ntest(two_sum_map, two_sum_tests)\n def two_sum_map(nums, target): \"\"\"Given a list of integers return the indices of the pair that sums to target.\"\"\" differences = {} for index in range(len(nums)): difference = target - nums[index] if nums[index] in differences: return differences[nums[index]], index differences[difference] = index test(two_sum_map, two_sum_tests) Testing two_sum_map...\nTests finished: 8 passed, 0 failed.\nIn\u00a0[7]: Copied!
def worst(size):\n \"\"\"Given a size, generate a worst-case problem instance for two sum.\"\"\"\n nums = [0] * (size - 2) + [1, 1]\n target = 2\n return (nums, target)\ndef worst(size): \"\"\"Given a size, generate a worst-case problem instance for two sum.\"\"\" nums = [0] * (size - 2) + [1, 1] target = 2 return (nums, target) In\u00a0[8]: Copied!
solutions = [two_sum_bf, two_sum_map]\ntime_functions(solutions, worst, start=100, double=4, chart=True)\nsolutions = [two_sum_bf, two_sum_map] time_functions(solutions, worst, start=100, double=4, chart=True)
Inputs generated by worst\n\nInput size two_sum_bf two_sum_map \n 100 454.4 5.7 \u00b5s\n 200 1906.9 11.1 \u00b5s\n 400 7516.0 22.5 \u00b5s\n 800 30797.2 45.9 \u00b5s\n 1600 125003.9 93.3 \u00b5s
The numbers printed before the chart represent the run-times of our solutions in microseconds (\u00b5s) for increasing input sizes.
On the chart, the data points for two_sum_bf almost instantly eclipse that of two_sum_map. It looks as if the run-times for two_sum_map are not growing at all, but we know by looking at numbers above that this is not the case.
Let us see if we can modify the inputs of time_functions for a better visual representation.
solutions = [two_sum_bf, two_sum_map]\ntime_functions(solutions, worst, start=1, double=4, text=False, chart=True)\nsolutions = [two_sum_bf, two_sum_map] time_functions(solutions, worst, start=1, double=4, text=False, chart=True)
We changed the initial input size to 1, and the trend of the run-times is a little clearer now. The Brute force algorithm's run-time's still accelerate off into the stratosphere, but we can see the separation and trend of the Mapping algorithm a little better.
"},{"location":"essays/example-two-sum-2/#two-sum-two-solutions","title":"Two Sum (two solutions)\u00b6","text":"Michael Snowden, 24 January 2024, last updated 16 March 2024
"},{"location":"essays/example-two-sum-2/#1-problem","title":"1 Problem\u00b6","text":"Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.
nums[i] $\\leq 109$target $\\leq 109$With our problem defined, the next step is to think of ways to solve it. This section presents two approaches to solving Two Sum: brute force, and mapping.
"},{"location":"essays/example-two-sum-2/#21-brute-force","title":"2.1 Brute force\u00b6","text":"Generally speaking, a brute force algorithm tries all possibilities, and selects a correct one. For this problem, the possibilities are all sums that can be obtained by pairing each number in nums with every other number, and the correct pair is selected when the sum matches target.
Brute force algorithm: An outer loop iterates through each number in nums, then for each number, an inner loop iterates nums again. For each pair of numbers, if their indices are different and their sum matches target, return their indices.
In the Brute force algorithm, we checked each pair of numbers in nums to see if the resulting sum was equal to target. Since we are already checking every number in the list, why not store some piece information from each number that will help us find our matching pair?
For every number in nums, we can map the difference between it and the target (target - number) to its corresponding index using a hashtable. This allows us to check the hashtable for matching numbers much faster.
Mapping algorithm: For each number in nums, if it's in the hashmap, return its index and the index mapped to it. Otherwise, calculate the difference (target - number) and map it to the corresponding index of number.
In this section we will implement and test the algorithms.
"},{"location":"essays/example-two-sum-2/#31-testing","title":"3.1 Testing\u00b6","text":"We start off by writing some tests.
To test the above solutions, we need to consider edge cases and other important functional tests. We should include tests for the minimum input size, and any extremes values that can be present. When integers are part of the input, and there are no restrictions, negative numbers and zero should be added to the tests.
"},{"location":"essays/example-two-sum-2/#32-implementations","title":"3.2 Implementations\u00b6","text":"The next cell implements the Brute force algorithm using nested for loops
In this section we measure the run-times of our solutions under certain conditions and discuss the results.
"},{"location":"essays/example-two-sum-2/#41-generating-inputs","title":"4.1 Generating inputs\u00b6","text":"Since time_functions from the algoesup library requires code to generate inputs, we shall write that first.
It is often useful to measure the run-times of a solution when it is doing the most work; this is called the worst-case. We want to generate inputs that will take our solution the most time to complete, and this happens when the two numbers that sum to target are the last two.
We now compare worst-case runtimes for both solutions. The input has an initial size of 100, and is doubled 4 times; the run times are measured for the initial size, then each time it is doubled.
"},{"location":"essays/example-two-sum-2/#5-conclusion","title":"5 Conclusion\u00b6","text":"We started this essay with the definition of the Two Sum problem. Next, we outlined two algorithms: brute force, and mapping . After that, we implemented and tested our solutions using Python, and in the penultimate section we used empirical testing and discussed the results. Now we must decide which of our algorithms is best.
The Brute force algorithm is not very efficient when it comes to run-times. When the size of the input increases the run-times increase by a large amount. The one redeeming aspect of this algorithm is the efficient memory usage which is achieved by not using any additional data structures like dictionaries.
In contrast, the Mapping algorithm is reasonably efficient in terms of run times, but this is achieved by using extra memory in the form of the dictionary. In the final analysis, the slow run-times of the brute force algorithm cannot be ignored. The small trade of memory for faster run-times is worth it in this instance. We therefore conclude the mapping algorithm is best.
"},{"location":"essays/example-two-sum-3/","title":"Two sum (three solutions)","text":"In this extended algorithmic essay we aim to solve the classic Two Sum problem from LeetCode. We are going to explore, analyse, and compare a selection of approaches with the end goal of finding a clear and efficient solution.
We assume the reader has an intermediate understanding of Python, including aspects like importing modules, using loops, and applying conditionals. Furthermore, Big-Oh notation is used to analyse the complexity of our solutions and we refer to terms such as binary search and brute force.
In\u00a0[1]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff pytype\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff pytype In\u00a0[2]: Copied!
from algoesup import test, time_functions, time_cases\nfrom algoesup import test, time_functions, time_cases In\u00a0[3]: Copied!
%load_ext algoesup.magics\n%ruff on\n%allowed on\n%load_ext algoesup.magics %ruff on %allowed on
ruff was activated\nallowed was activated\nIn\u00a0[4]: Copied!
two_sum_tests = [\n # [\"description\", nums, target, expected_output]\n [\"minimum size for nums\", [1, 2], 3, (0, 1)],\n [\"non-adjacent indices\", [1, 4, 9, 7], 8, (0, 3)],\n [\"first two elements\", [5, 7, 1, 2, 8], 12, (0, 1)],\n [\"last two elements\", [1, 3, 5, 7, 8], 15, (3, 4)],\n [\"repeated elements\", [6, 2, 3, 2], 4, (1, 3)],\n [\"max and min range\", [-109, 109, 0], 0, (0, 1)],\n [\"lowest target value\", [-50, 1, -59], -109, (0, 2)],\n [\"highest target value\", [50, 1, 59], 109, (0, 2)],\n]\ntwo_sum_tests = [ # [\"description\", nums, target, expected_output] [\"minimum size for nums\", [1, 2], 3, (0, 1)], [\"non-adjacent indices\", [1, 4, 9, 7], 8, (0, 3)], [\"first two elements\", [5, 7, 1, 2, 8], 12, (0, 1)], [\"last two elements\", [1, 3, 5, 7, 8], 15, (3, 4)], [\"repeated elements\", [6, 2, 3, 2], 4, (1, 3)], [\"max and min range\", [-109, 109, 0], 0, (0, 1)], [\"lowest target value\", [-50, 1, -59], -109, (0, 2)], [\"highest target value\", [50, 1, 59], 109, (0, 2)], ] In\u00a0[5]: Copied!
def two_sum_bf(nums: list, target: int) -> tuple[int, int]:\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\n\n Preconditions:\n len(nums) >= 2\n -109 <= nums[i] <= 109\n -109 <= target <= 109\n Exactly one pair a and b in nums has a + b = target\n \"\"\"\n for index_1 in range(len(nums)):\n for index_2 in range(len(nums)):\n if index_1 != index_2 and nums[index_1] + nums[index_2] == target:\n return index_1, index_2\n\ntest(two_sum_bf, two_sum_tests)\ndef two_sum_bf(nums: list, target: int) -> tuple[int, int]: \"\"\"Given a list of integers return the indices of the pair that sums to target. Preconditions: len(nums) >= 2 -109 <= nums[i] <= 109 -109 <= target <= 109 Exactly one pair a and b in nums has a + b = target \"\"\" for index_1 in range(len(nums)): for index_2 in range(len(nums)): if index_1 != index_2 and nums[index_1] + nums[index_2] == target: return index_1, index_2 test(two_sum_bf, two_sum_tests)
Testing two_sum_bf...\nTests finished: 8 passed, 0 failed.\n
Next up is the approach that uses sorting.
In\u00a0[6]: Copied!def two_sum_sort(nums: list, target: int) -> tuple[int, int]:\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\n\n Preconditions:\n len(nums) >= 2\n -109 <= nums[i] <= 109\n -109 <= target <= 109\n Exactly one pair a and b in nums has a + b = target\n \"\"\"\n pairs = []\n for index in range(len(nums)):\n pairs.append((nums[index], index))\n pairs.sort()\n start = 0\n end = len(nums) - 1\n while start < end:\n current_sum = pairs[start][0] + pairs[end][0]\n if current_sum == target:\n # return the indices in ascending order for reliable testing\n lower_index = min(pairs[start][1], pairs[end][1])\n upper_index = max(pairs[start][1], pairs[end][1])\n indices = (lower_index, upper_index)\n return indices\n if current_sum < target:\n start = start + 1\n else:\n end = end - 1\n\ntest(two_sum_sort, two_sum_tests)\ndef two_sum_sort(nums: list, target: int) -> tuple[int, int]: \"\"\"Given a list of integers return the indices of the pair that sums to target. Preconditions: len(nums) >= 2 -109 <= nums[i] <= 109 -109 <= target <= 109 Exactly one pair a and b in nums has a + b = target \"\"\" pairs = [] for index in range(len(nums)): pairs.append((nums[index], index)) pairs.sort() start = 0 end = len(nums) - 1 while start < end: current_sum = pairs[start][0] + pairs[end][0] if current_sum == target: # return the indices in ascending order for reliable testing lower_index = min(pairs[start][1], pairs[end][1]) upper_index = max(pairs[start][1], pairs[end][1]) indices = (lower_index, upper_index) return indices if current_sum < target: start = start + 1 else: end = end - 1 test(two_sum_sort, two_sum_tests)
Testing two_sum_sort...\nTests finished: 8 passed, 0 failed.\n
Finally, the mapping algorithm is implemented using Python's dict.
def two_sum_map(nums: list, target: int) -> tuple[int, int]:\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\n\n Preconditions:\n len(nums) >= 2\n -109 <= nums[i] <= 109\n -109 <= target <= 109\n Exactly one pair a and b in nums has a + b = target\n \"\"\"\n differences: dict[int, int] = {} # allowed\n for index in range(len(nums)):\n difference = target - nums[index]\n if nums[index] in differences:\n return differences[nums[index]], index\n differences[difference] = index\n\ntest(two_sum_map, two_sum_tests)\n def two_sum_map(nums: list, target: int) -> tuple[int, int]: \"\"\"Given a list of integers return the indices of the pair that sums to target. Preconditions: len(nums) >= 2 -109 <= nums[i] <= 109 -109 <= target <= 109 Exactly one pair a and b in nums has a + b = target \"\"\" differences: dict[int, int] = {} # allowed for index in range(len(nums)): difference = target - nums[index] if nums[index] in differences: return differences[nums[index]], index differences[difference] = index test(two_sum_map, two_sum_tests) Testing two_sum_map...\nTests finished: 8 passed, 0 failed.\n
The brute force algorithm comes out on top in terms of simplicity, it is just a case of checking every pair of numbers. The double pointer approach seems like the most convoluted with the mapping differences algorithm somewhere in the middle of the two.
In\u00a0[8]: Copied!def best(size: int) -> tuple[list[int], int]:\n \"\"\"Given a size, generate a best case instance for Two Sum.\n\n Preconditions: size >= 2\n \"\"\"\n nums = [1, 1] + [0] * (size - 2)\n target = 2\n return (nums, target)\n\ndef normal(size: int) -> tuple[list[int], int]:\n \"\"\"Given a size, generate a normal case instance for Two Sum.\n\n Preconditions: size >= 2\n \"\"\"\n nums = [0] * size\n nums[size // 2 - 1:size // 2 + 1] = [1, 1]\n target = 2\n return (nums, target)\n\ndef worst(size: int) -> tuple[list[int], int]:\n \"\"\"Given a size, generate a worst case instance for Two Sum.\n\n Preconditions: size >= 2\n \"\"\"\n nums = [0] * (size - 2) + [1, 1]\n target = 2\n return (nums, target)\ndef best(size: int) -> tuple[list[int], int]: \"\"\"Given a size, generate a best case instance for Two Sum. Preconditions: size >= 2 \"\"\" nums = [1, 1] + [0] * (size - 2) target = 2 return (nums, target) def normal(size: int) -> tuple[list[int], int]: \"\"\"Given a size, generate a normal case instance for Two Sum. Preconditions: size >= 2 \"\"\" nums = [0] * size nums[size // 2 - 1:size // 2 + 1] = [1, 1] target = 2 return (nums, target) def worst(size: int) -> tuple[list[int], int]: \"\"\"Given a size, generate a worst case instance for Two Sum. Preconditions: size >= 2 \"\"\" nums = [0] * (size - 2) + [1, 1] target = 2 return (nums, target)
First let us see the run-times of two_sum_bf for best, normal and worst-case instances. Note the input size starts at 100 and is doubled 4 times reaching 1600 for the last data point.
input_generators = [worst, normal, best]\ntime_cases(two_sum_bf, input_generators, start=100, double=4, chart=True)\ninput_generators = [worst, normal, best] time_cases(two_sum_bf, input_generators, start=100, double=4, chart=True)
Run-times for two_sum_bf\n\nInput size worst normal best \n 100 454.6 228.8 0.3 \u00b5s\n 200 1817.9 1046.2 0.3 \u00b5s\n 400 7488.9 3722.6 0.3 \u00b5s\n 800 30940.9 15670.3 0.3 \u00b5s\n 1600 124206.2 62150.1 0.3 \u00b5s
We can see from the chart and run-times above, that our analysis of quadratic time complexity for the worst-case seems to line up with the data. As we double the input size, the run-times quadruple. For the best case, the run-times generally stay the same for increasing inputs suggesting constant time complexity. The normal case is somewhere in the middle of the two.
Now let us do the same for two_sum_map.
input_generators = [worst, normal, best]\ntime_cases(two_sum_map, input_generators, start=100, double=4, chart=True)\ninput_generators = [worst, normal, best] time_cases(two_sum_map, input_generators, start=100, double=4, chart=True)
Run-times for two_sum_map\n\nInput size worst normal best \n 100 5.7 3.0 0.3 \u00b5s\n 200 11.2 5.7 0.3 \u00b5s\n 400 22.7 11.2 0.3 \u00b5s\n 800 46.3 22.7 0.3 \u00b5s\n 1600 93.5 46.4 0.3 \u00b5s
The first thing to note is the dramatic reduction in size of the run-times. The scales on the y-axis differ by orders of magnitude. Also, the plot for our worst-case on this chart has a much straighter line with run-times doubling in proportion with input size. This aligns with our prediction of linear time complexity.
In\u00a0[11]: Copied!solutions = [two_sum_bf, two_sum_sort, two_sum_map]\ntime_functions(solutions, worst, start=100, double=4, chart=True)\nsolutions = [two_sum_bf, two_sum_sort, two_sum_map] time_functions(solutions, worst, start=100, double=4, chart=True)
Inputs generated by worst\n\nInput size two_sum_bf two_sum_sort two_sum_map \n 100 455.2 14.5 5.7 \u00b5s\n 200 1816.7 28.4 11.1 \u00b5s\n 400 7499.5 57.4 22.7 \u00b5s\n 800 30764.1 116.3 46.3 \u00b5s\n 1600 124771.8 236.4 93.6 \u00b5s
The run-times for two_sum_bf almost instantly eclipse that of two_sum_sort and two_sum_map.On the chart it looks as if the run-times for two_sum_sort and two_sum_map are not growing at all, but we know by looking at the run-times above that this is not the case. Let us see if we can adjust the inputs of time_functions so the growth rates of the fastest two functions have a better visual representation in the chart.
solutions = [two_sum_bf, two_sum_sort, two_sum_map]\ntime_functions(solutions, worst, start=1, double=4, text=False, chart=True)\nsolutions = [two_sum_bf, two_sum_sort, two_sum_map] time_functions(solutions, worst, start=1, double=4, text=False, chart=True)
The point at which the growth rates start to diverge is much clearer now. The brute force approach's run-times still accelerate off into the stratosphere, but we can see the separation and trend of the sorting and mapping algorithms.
"},{"location":"essays/example-two-sum-3/#two-sum-three-solutions","title":"Two sum (three solutions)\u00b6","text":"Michael Snowden, 25 January 2024, last updated 16 March 2024
"},{"location":"essays/example-two-sum-3/#1-problem","title":"1 Problem\u00b6","text":"To effectively solve Two Sum, it is crucial we thoroughly understand the problem. We need to identify the inputs, outputs and the relationship between them.
Leetcode provides the following problem description.
\"Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.\"
nums[i] $\\leq 109$target $\\leq 109$We can extract some important information from their description, namely the pre- and post-conditions.
Preconditions:
nums[i] $\\leq 109$target $\\leq 109$a and b in nums has a + b = targetPostconditions:
Let indices be the output, then:
len(indices) = 2;nums[indices[0]] + nums[indices[1]] = targetThe preconditions must be satisfied for our algorithms to be defined, and the postconditions must be satisfied for our algorithms to be correct.
"},{"location":"essays/example-two-sum-3/#2-algorithms","title":"2 Algorithms\u00b6","text":"With our problem defined, the next step is to think of ways to solve it. This section presents three distinct approaches to solving Two sum: brute force, sorting and mapping.
"},{"location":"essays/example-two-sum-3/#21-brute-force","title":"2.1 Brute force\u00b6","text":"Generally speaking, a brute force algorithm tries all possibilities, and selects a correct one. For this problem, the possibilities are all sums that can be obtained by pairing each number in nums with every other number, and the correct pair is identified if the sum matches target. We are checking all possible sums, so we are sure to find our indices if they exist. Looking back at the preconditions, we can see that each problem instance must have exactly one pair that sums to target. Hence this approach is guaranteed to find a solution, as long as our preconditions are met.
Getting any working solution regardless of efficiency can be an important first step. Sometimes we need to solve a problem quickly, and more importantly it gets us thinking through it, which can often lead to additional solutions.
Brute force algorithm: An outer loop iterates through each number in nums, then for each number, an inner loop iterates nums again. For each pair of numbers, if their indices are different and their sum matches target, return their indices.
1. for each index_1 from 0 to len(nums)-1:\n 1. for each index_2 from 0 to len(nums)-1:\n 1. if index_1 != index_2 and nums[index_1] + nums[index_2] == target:\n 1. let indices be (index_1, index_2)\n 2. stop\n
Let n = len(nums), then this algorithm has two nested for loops that do n iterations each. The operations performed within the inner loop are constant time, meaning this solution will do at most n $\\times$ n $\\times$ O(1) steps. Thus, the worst-case time complexity is O(n $^2$). In the best-case, the first and second numbers in nums sum to target. No matter the size of nums, the run-times would not increase. Therefore, the best-case time complexity would be O(1).
For many computational problems a good question to ask is: will sorting the inputs simplify the problem and lead to a more efficient solution? In this case, the answer is yes, we can exploit the properties of a sorted input in a similar way to binary search. Rather than focusing on the middle of the sequence and reducing the search space by half, we keep track of the two ends with position variables and have reduce the search space by one each time. This kind of approach is commonly referred to as a \"double pointer algorithm\" named after the two position variables.
Before we move on to a formal description of the algorithm, we need to consider a crucial aspect of the Two Sum problem: it requires indices to be returned. This has implications for our solution: direct sorting of nums is not possible because the original index positions would be altered. Thus, any additional data structures we use must keep track of the corresponding indices from elements of nums. Keeping this in mind, here is the description of our algorithm.
With sorting algorithm: Create a pair (number, index) for each number in nums. Add each pair to a list pairs, then sort the list into ascending order based on the numbers. Initialise two variables start and end to be 0 and len(nums) - 1 respectively. While start $\\neq$ end sum the numbers in pairs corresponding to the indices start and end. If the sum is less than target, move start to the right by incrementing its value by one. If the sum is greater than target, move end to the left by decrementing its value by one. If the sum matches target then return the indices of both numbers.
The logic of this strategy is as follows. The sum of the numbers at positions start and end in our pairs list will have one of the following three cases: the sum can be equal to, greater than or less than target. If the sum is equal to target, then we have found our solution and can return the indices. If the sum is less than target, we need to increase the value of our sum; the only way to do this is by moving start to the right. Remember we have sorted the list, so all values to the right are greater. If our sum is greater than target we need to decrease the value of our sum, and the only way to do that by moving end to the left.
1. let pairs be an empty list\n2. for each index from 0 to len(nums):\n 1. let `pair be (nums[index], index)\n 2. append pair to `pairs`\n3. let pairs be sorted by value at first index\n4. let start = 0\n5. let end = len(nums) -1\n6. while start != end:\n 1. pair_sum = pairs[start][0] + pairs[end][0]\n 2. if pairs_sum = target:\n 1. let indices be (pairs[start][1], pairs[end][1])\n 2. stop\n 3. otherwise if pairs_sum > target:\n 1. let end = end - 1\n 4. otherwise:\n 1. let start = start + 1\n
The important parts of this algorithm with respect analysing time complexity are: the for loop at step number two, the sorting operation at step number three and the while loop at step number six.
Let n = len(nums), then the for loop always does n iterations, and we will assume the sorting operation has worst-case complexity of O(n log(n)) and best-case of O(n), that just leaves the while loop. The while loop will do at most n iterations in a scenario where one of the variables start or end stays in place and the other is incremented until they are next to each other.
It is clear now that the sorting operation will dominate this approach when it comes to time complexity. Therefore, this algorithm has an overall worst-case time complexity of O(n log(n)) and a best-case of O(n).
"},{"location":"essays/example-two-sum-3/#23-mapping","title":"2.3 Mapping\u00b6","text":"In the previous algorithm we paired each number in nums with its index out of necessity. We wanted to sort nums without loosing the original paring of number to index. This action of pairing numbers to indices is a useful idea; what if instead of pairing a number directly to its index, we paired the difference between our number and the target (i.e. target - number) to its index? If we did that, then finding our pair would be a case of checking if current number is in the pairs list.
This is a good start, but we still have a problem, the lookup operation takes linear time for a list. We need an alternative data structure, one with much efficient lookup times. If fast lookup times are required, then we should always consider a hashtable. This data structure is known informally by many different names such as dictionary, hashmap, map and associative array. A key property of this data structure is the lookup operation has constant time complexity in the average case.
For every number in nums, we can map the difference between it and the target (target - number) to its corresponding index using a hashtable. This allows us to check the hashmap for matching numbers in constant time.
Mapping algorithm: For each number in nums, if its in the hashmap, return its index and the index mapped to it. Otherwise, calculate the difference (target - number) and map it to the corresponding index of number.
1. let differences be an empty dictionary\n2. for index from 0 to len(nums) - 1:\n 1. if nums[index] in differences:\n 1.let indices be (differences[nums[index]], index)\n 2. stop\n 2. otherwise:\n 1. let difference = target - nums[index]\n 2. let differences[difference] = index\n
Let n = len(nums), then this algorithm has a single loop that does n iterations. Because we are using a hashmap, all the operations performed in the loop are done in constant time. Thus, our mapping algorithm has O(n) time complexity in in the worst-case. Similar to the brute force approach, if the correctly summing numbers are in the first two positions of nums, then the run-times will be unaffected by increasing input sizes, giving a best-case complexity of O(1).
Many times a brute force approach is a good starting point; it is a simple strategy that is easy to implement. Moreover, this strategy is efficient in terms of its memory usage when compared to the other algorithms; it does not use additional data structures. However, this approach has an undesirable O(n $^2$) worst-case time complexity. Every time we double the input size, the run-times increase fourfold.
Our next approach used sorting to endow our list with properties useful for searching. This algorithm is perhaps the most convoluted and maybe harder to think through relative to the others. Furthermore, it requires additional memory compared to the brute force approach. The benefits of the strategy are the O(n log(n)) worst-case time complexity which improves considerably on the brute force algorithm.
The third solution made a single pass through nums and used a hashtable to map differences to indexes. While not as simple as the brute force algorithm, this approach is not hard to follow nor understand; everything is carried out in a single loop. On the other hand, this approach has the additional memory overhead of the hashtable itself, which needs to be taken into account. The main advantage with this approach is the O(n) time complexity for the worst-case, making it the most efficient when it comes to scaling run-times with input size.
When considering all three approaches, and taking into account aspects of efficiency as well as readability, the mapping algorithm seems to come out on top. It makes that that classic space-time trade off i.e sacrifices some memory efficiency for time efficiency, but the simplicity of the approach combined with the efficient time complexity makes it a worth while exchange.
"},{"location":"essays/example-two-sum-3/#3-code","title":"3 Code\u00b6","text":"In this section we will implement the algorithms. We shall do so using a basic subset of Python in the hope of making our code as language agnostic as possible.
Throughout this section we will make use of code quality tools such as linters and type checkers to help us meet the standards expected for clean readable and error free code.
"},{"location":"essays/example-two-sum-3/#31-preparation-and-imports","title":"3.1 Preparation and imports\u00b6","text":"The next two cells set up the automatic type checking linting and Construct checking for our code cells. We also import some of the functions we will use to test, time and generate instances for our solutions.
If one or more of the styling or type checking ideals are violated, the warnings will be printed alongside the corresponding line number underneath the offending cell.
"},{"location":"essays/example-two-sum-3/#32-testing","title":"3.2 Testing\u00b6","text":"Before We start implementing our algorithms, we write some tests. The test() function from the algoesup library is a simple way to test for correctness. It takes a function and a test table then reports any failed tests.
To test the algorithms, we need to consider edge cases and other important functional tests. Edge cases often occur at the extreme ends of the spectrum of allowed inputs or outputs, they should ideally test unexpected conditions that might reveal bugs in the code. For the Two Sum problem, we should test the minimum size for nums and also the extremes of the values that can be present. We should include negative numbers and zero in our tests because integers are present in the inputs.
The cell below contains our test table, note the descriptions of each case in the first column, and how the boundary cases, negative numbers and zero are all present in the table.
"},{"location":"essays/example-two-sum-3/#33-implementations","title":"3.3 Implementations\u00b6","text":"The next cell implements the brute force algorithm using nested for loops and a conditional to check for the correct pair. Note how this conditional looks similar to one of the postconditions; this is a good sign.
In this section we will measure the run-times of our solutions under various conditions to see if our analysis matches the results.
"},{"location":"essays/example-two-sum-3/#41-generating-inputs","title":"4.1 generating inputs\u00b6","text":"time_functions and time_cases from the algoesup library require a function that generates problem instances of a given size. We want to be able to generate instances that correspond to best, normal and worst cases for the solutions were appropriate.
The best normal and worst case scenarios might not always be the same for each algorithm, for example, the best-case for two_sum_bf and two_sum_map would be when the first two numbers encountered sum to target but this is not the case for two_sum_sort where the best-case would be dependent on the sorting algorithm.
Since two_sum_bf and two_sum_map share the same best- and worst-case scenarios, we shall focus on those for our input generators. For the normal-case the matching numbers will be in the middle two positions of nums
Let us now compare the worst-case run-times for all three solutions side by side.
"},{"location":"essays/example-two-sum-3/#5-conclusion","title":"5 Conclusion\u00b6","text":"We started this essay by defining the problem. We came up with three algorithms that used different approaches: brute force, sorting and mapping, then analysed the time complexity of each one. Next, we implemented and tested our solutions using Python, and in the penultimate section used empirical testing to see if our analysis matched the results. Now we must decide which of our algorithms is best.
The brute force approach, unsurprisingly, is not very efficient when it comes to run-times. We suspected this would be the case, then the empirical testing confirmed it. Its only positive attributes were its simplicity and efficient memory usage.
We are now left with a choice between the sorting and mapping approaches and I think there is a clear winner between the two. The mapping approach is more efficient in its worst-case complexity with O(n) compared to O(n log(n)) of the sorting, and on the surface seems simpler and easier to implement. Moreover, the mapping approach has the potential to be more memory efficient. For example, the sorting approach always has an auxiliary data structure the same size as nums, whereas the size of the dictionary will grow dynamically, only becoming the same size as nums in the worst case. Therefore, we must conclude the mapping algorithm is best.
This algorithmic essay template is for students of data structures and algorithms (DSA) courses. Throughout the template, there are links to relevant sections of our Writing and Coding Guide. Replace any text in italics by yours and delete this paragraph.
The introduction explains what the essay is about, the problem you are solving, and what you assume the reader to know. See our guidance on choosing a problem, writing the text and structuring the essay. This template follows the first structure in the guide. You don't need to change the following code cells.
In\u00a0[\u00a0]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff pytype\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff pytype In\u00a0[\u00a0]: Copied!
from algoesup import test, time_cases, time_functions\nfrom algoesup import test, time_cases, time_functions
For information on what the following commands do, see our guide's sections on type checking and linting and remove this paragraph.
In\u00a0[\u00a0]: Copied!%load_ext algoesup.magics\n# check the code's style\n%ruff on\n# check the data types\n%pytype on\n# optional: flag the Python constructs not taught in M269, our DSA course\n%allowed on\n%load_ext algoesup.magics # check the code's style %ruff on # check the data types %pytype on # optional: flag the Python constructs not taught in M269, our DSA course %allowed on In\u00a0[\u00a0]: Copied!
tests = [\n # Each line is a list or tuple of the form:\n # (description, input1, input2, ..., expected_output),\n]\ntests = [ # Each line is a list or tuple of the form: # (description, input1, input2, ..., expected_output), ] In\u00a0[\u00a0]: Copied!
# Replace solution_one with a more descriptive name.\ndef solution_one():\n # Implement your solution here\n pass\n\ntest(solution_one, tests)\n# Replace solution_one with a more descriptive name. def solution_one(): # Implement your solution here pass test(solution_one, tests) In\u00a0[\u00a0]: Copied!
# Replace solution_two with a more descriptive name.\ndef solution_two():\n # Implement your solution here\n pass\n\ntest(solution_two, tests)\n# Replace solution_two with a more descriptive name. def solution_two(): # Implement your solution here pass test(solution_two, tests) In\u00a0[\u00a0]: Copied!
# Replace solution_n with a more descriptive name.\ndef solution_n():\n # Implement your solution here\n pass\n\ntest(solution_n, tests)\n# Replace solution_n with a more descriptive name. def solution_n(): # Implement your solution here pass test(solution_n, tests) In\u00a0[\u00a0]: Copied!
def best_case(size: int) -> tuple[...]:\n # Implement your best-case input generator here.\n pass\ndef best_case(size: int) -> tuple[...]: # Implement your best-case input generator here. pass In\u00a0[\u00a0]: Copied!
def worst_case(size: int) -> tuple[...]:\n # Implement your worst-case input generator here.\n pass\ndef worst_case(size: int) -> tuple[...]: # Implement your worst-case input generator here. pass In\u00a0[\u00a0]: Copied!
def normal_case(size: int) -> tuple[...]:\n # Implement your normal-case input generator here.\n pass\ndef normal_case(size: int) -> tuple[...]: # Implement your normal-case input generator here. pass In\u00a0[\u00a0]: Copied!
cases = [best_case, normal_case, worst_case]\n# Change solution_n to the name of your solution.\ntime_cases(solution_n, cases, start=10, double=4)\ncases = [best_case, normal_case, worst_case] # Change solution_n to the name of your solution. time_cases(solution_n, cases, start=10, double=4)
Analyse the results. See the interpreting run-times section of our guide.
In\u00a0[\u00a0]: Copied!# Change solution_one, solution_two, and solution_n to the names of your solutions.\nalgorithms = [solution_one, solution_two, solution_n]\n# Replace normal_case with best_case or worst_case, if you wish.\ntime_functions(algorithms, normal_case, 1000, 4, chart=True)\n# Change solution_one, solution_two, and solution_n to the names of your solutions. algorithms = [solution_one, solution_two, solution_n] # Replace normal_case with best_case or worst_case, if you wish. time_functions(algorithms, normal_case, 1000, 4, chart=True)
Analyse the results. See the interpreting run-times section of our guide.
"},{"location":"essays/template-data-structures/#your-essays-title","title":"Your essay's title\u00b6","text":"Your (and any co-author's) name, current date
"},{"location":"essays/template-data-structures/#1-tests","title":"1 Tests\u00b6","text":"This section describes and defines the tests you will use to check your solutions. See the testing section of our guide.
"},{"location":"essays/template-data-structures/#2-algorithms","title":"2 Algorithms\u00b6","text":"This section outlines some algorithms that solve the problem. See the algorithms section of our guide.
"},{"location":"essays/template-data-structures/#21-first-algorithm-name","title":"2.1 First algorithm name\u00b6","text":"Describe your first strategy or approach.
Algorithm 1: Briefly describe your first algorithm.
Analyse at least the worst-case time complexity of your first algorithm.
"},{"location":"essays/template-data-structures/#22-second-algorithm-name","title":"2.2 Second algorithm name\u00b6","text":"Describe your second strategy or approach.
Algorithm 2: Briefly describe your second algorithm.
Analyse at least the worst-case time complexity of your second algorithm.
"},{"location":"essays/template-data-structures/#2n-nth-algorithm-name","title":"2.n nth algorithm name\u00b6","text":"Describe your nth strategy or approach.
Algorithm n: Briefly describe your nth algorithm.
Analyse at least the worst-case time complexity of your nth algorithm.
"},{"location":"essays/template-data-structures/#2n1-summary","title":"2.n+1 Summary\u00b6","text":"This section compares the previously outlined algorithms to inform implementation decisions.
"},{"location":"essays/template-data-structures/#3-code","title":"3 Code\u00b6","text":"This section implements and tests only the most promising algorithms. See the code section of our guide.
"},{"location":"essays/template-data-structures/#4-performance","title":"4 Performance\u00b6","text":"This section measures and compares the run-times of your implementations, so that you can check them against your earlier complexity analysis.
"},{"location":"essays/template-data-structures/#41-generating-inputs","title":"4.1 Generating inputs\u00b6","text":"Briefly describe your strategy and reasoning for generating the inputs.
"},{"location":"essays/template-data-structures/#42-best-normal-and-worst-run-times","title":"4.2 Best, normal and worst run-times\u00b6","text":"State which solutions(s) will be timed with best-, normal- or worst-case inputs. See the comparing cases and charting run-times sections of our guide.
"},{"location":"essays/template-data-structures/#43-fastest-and-slowest-algorithm","title":"4.3 Fastest and slowest algorithm\u00b6","text":"Compare the run times of all your solutions for the same case. See the comparing functions and charting run-times sections of our guide.
"},{"location":"essays/template-data-structures/#5-concluding-remarks","title":"5 Concluding remarks\u00b6","text":"Summarise your findings and conclude which solution is best.
After completing a draft of your essay, do a final check and then see the feedback guide on how to ask for, give, and handle comments.
"},{"location":"essays/template-data-structures/#6-acknowledgements","title":"6 Acknowledgements\u00b6","text":"Credit those who helped you create the essay. See the crediting feedback section of our guide.
"},{"location":"essays/template-intro-programming/","title":"Your essay's title","text":"This algorithmic essay template is for students of introductory programming courses. Throughout the template, there are links to relevant sections of our Writing and Coding Guide. Replace any text in italics by yours and delete this paragraph.
The introduction explains what the essay is about, the problem you are solving, and what you assume the reader to know. See our guidance on choosing a problem, writing the text and structuring the essay. This template follows the second structure in the guide. You don't need to change the following code cells.
In\u00a0[\u00a0]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff In\u00a0[\u00a0]: Copied!
# import functions to test the code and to measure the execution time\nfrom algoesup import test, time_functions_int\n# import functions to test the code and to measure the execution time from algoesup import test, time_functions_int
For information on what the following commands do, see our guide's section on linting and remove this paragraph.
In\u00a0[\u00a0]: Copied!%load_ext algoesup.magics\n# check the code's style\n%ruff on\n# optional: flag the Python constructs not taught in TM112, our introductory course\n%allowed on --config tm112.json\n%load_ext algoesup.magics # check the code's style %ruff on # optional: flag the Python constructs not taught in TM112, our introductory course %allowed on --config tm112.json In\u00a0[\u00a0]: Copied!
tests = [\n # Each line is a list or tuple of the form:\n # (description, input1, input2, ..., expected_output),\n]\ntests = [ # Each line is a list or tuple of the form: # (description, input1, input2, ..., expected_output), ] In\u00a0[\u00a0]: Copied!
def solution_one():\n # Implement your solution here\n pass\n\ntest(solution_one, tests)\ndef solution_one(): # Implement your solution here pass test(solution_one, tests) In\u00a0[\u00a0]: Copied!
def solution_two():\n # Implement your solution here\n pass\n\ntest(solution_two, tests)\ndef solution_two(): # Implement your solution here pass test(solution_two, tests) In\u00a0[\u00a0]: Copied!
# The next line assumes your functions have a single integer as input.\ntime_functions_int([solution_one, solution_two])\n# The next line assumes your functions have a single integer as input. time_functions_int([solution_one, solution_two])
Analyse the results.
"},{"location":"essays/template-intro-programming/#your-essays-title","title":"Your essay's title\u00b6","text":"Your (and any co-author's) name, current date
"},{"location":"essays/template-intro-programming/#1-tests","title":"1 Tests\u00b6","text":"This section describes and defines the tests you will use to check your solutions. See the testing section of our guide.
"},{"location":"essays/template-intro-programming/#2-solutions","title":"2 Solutions\u00b6","text":""},{"location":"essays/template-intro-programming/#21-first-solution-name","title":"2.1 First solution name\u00b6","text":"Describe your first strategy or approach, then implement and test it.
"},{"location":"essays/template-intro-programming/#22-second-solution-name","title":"2.2 Second solution name\u00b6","text":"Describe your second strategy or approach, then implement and test it.
"},{"location":"essays/template-intro-programming/#3-performance","title":"3 Performance\u00b6","text":"This optional section compares the performance of your solutions to see which is fastest.
"},{"location":"essays/template-intro-programming/#4-concluding-remarks","title":"4 Concluding remarks\u00b6","text":"Summarise your findings and conclude which solution is best.
After completing a draft of your essay, do a final check and then see the feedback guide on how to ask for, give, and handle comments.
"},{"location":"essays/template-intro-programming/#5-acknowledgements","title":"5 Acknowledgements\u00b6","text":"Credit those who helped you create the essay. See the crediting feedback section of our guide.
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Algorithmic Essays","text":"These documents provide guidance to help you write, critique, and share algorithmic essays.
We define algorithmic essays as short reports, with code, that explain and compare alternative approaches to solving a computational problem.
If you\u2019re a student, writing algorithmic essays benefits you in various ways:
If you\u2019re an educator, you can copy our resources from the GitHub repository and adapt them to your course, due to our permissive licence (see below).
Example
We provide some example essays to illustrate what they are.
While many approaches to writing algorithmic essays are possible, we recommend using Jupyter notebooks, the most widely used medium for mixing text and executable code.
If you\u2019re a student on M269, our data structures and algorithms course, you can write an essay with your existing software and share it on the forums.
Get started (M269)
If you prefer a \u2018Google Docs\u2019-like environment for collaborative authoring and commenting on essays, we suggest Deepnote or Google\u2019s Colaboratory (Colab for short):
We have no affiliation, commercial or otherwise, with Deepnote or Google. We chose them based on our comparison of Jupyter notebook platforms.
Get started (Deepnote) Get started (Colab)
"},{"location":"#acknowledgements","title":"Acknowledgements","text":"This project was partly funded by the UK\u2019s Council of Professors and Heads of Computing, under the Special Projects grant scheme, in May 2023.
"},{"location":"#licences","title":"Licences","text":"The code and text in this repository are Copyright \u00a9 2023\u20132024 by The Open University, UK. The code is licensed under a BSD 3-clause licence. The text is licensed under a Creative Commons Attribution 4.0 International Licence.
"},{"location":"coding/","title":"Coding guide","text":"In\u00a0[1]: Copied!from algoesup import test\n\n# function to be tested\ndef absolute_difference(x: int, y: int) -> int:\n \"\"\"Return the absolute value of the difference between x and y.\"\"\"\n return x - y # deliberately wrong, should be abs(x - y)\n\n# fmt: off\n# unit tests in tabular form, one test per row\nunit_tests = [\n # test case, x, y, expected result\n (\"x == y\", 1, 1, 0),\n (\"x > y\", 10, -1, 11),\n (\"x < y\", -1, 10, 11),\n]\n# fmt: on\n\n# run the function on all test inputs and compare the actual and expected outputs\ntest(absolute_difference, unit_tests)\nfrom algoesup import test # function to be tested def absolute_difference(x: int, y: int) -> int: \"\"\"Return the absolute value of the difference between x and y.\"\"\" return x - y # deliberately wrong, should be abs(x - y) # fmt: off # unit tests in tabular form, one test per row unit_tests = [ # test case, x, y, expected result (\"x == y\", 1, 1, 0), (\"x > y\", 10, -1, 11), (\"x < y\", -1, 10, 11), ] # fmt: on # run the function on all test inputs and compare the actual and expected outputs test(absolute_difference, unit_tests)
Testing absolute_difference...\nx < y FAILED: -11 instead of 11\nTests finished: 2 passed, 1 failed.\n
A unit test consists of the input values to pass to your function and the output value you're expecting. The library requires a short descriptive string for each unit test, so that it can indicate which tests failed. The library expects unit tests to be in tabular format: one row per test, and one column for the description, one column for each input, and one column for the expected output. In the example above, the test table is a list of tuples, but it could as well be a list of lists, a tuple of lists, or a tuple of tuples.
You should reuse the test table for all solutions, because they're about the same problem. Here's a correct function that passes all test cases.
In\u00a0[2]: Copied!def absolute_difference_without_abs(x: int, y: int) -> int:\n \"\"\"Return the absolute value of the difference between x and y.\n\n This solution doesn't use the built-in abs() function.\n \"\"\"\n if x > y:\n return x - y\n else:\n return y - x\n\ntest(absolute_difference_without_abs, unit_tests) # same test table\ndef absolute_difference_without_abs(x: int, y: int) -> int: \"\"\"Return the absolute value of the difference between x and y. This solution doesn't use the built-in abs() function. \"\"\" if x > y: return x - y else: return y - x test(absolute_difference_without_abs, unit_tests) # same test table
Testing absolute_difference_without_abs...\nTests finished: 3 passed, 0 failed.\nIn\u00a0[3]: Copied!
%load_ext algoesup.magics\n%load_ext algoesup.magics
(Magics are special commands that can change the behaviour of running a code cell.) You can now turn on type checking as follows.
In\u00a0[4]: Copied!%pytype on\n%pytype on
pytype was activated\n
Words that start with % are special commands ('magics') for IPython, the Python interpreter used by Jupyter notebooks. The %pytype command, provided by our library, activates Google's pytype type checker.
Once the type checker is activated, it checks each cell immediately after it's executed. In this way you can detect and fix errors as you write and run each code cell. Here's an example of what happens.
In\u00a0[5]: Copied!def double(x: int) -> int:\n \"\"\"Return twice the value of x.\"\"\"\n return x * 2\n\ndouble([4])\ndef double(x: int) -> int: \"\"\"Return twice the value of x.\"\"\" return x * 2 double([4]) Out[5]:
[4, 4]
pytype found issues:
The function is executed and produces an output because lists can also be 'multiplied' with an integer, but the type checker detects that line 5 should have passed integers, not lists of integers, to the function. Clicking on the error name in square brackets leads you to pytype's website, with more info.
When a type checker only processes one cell at a time, it is missing the wider context, like the previously defined functions. Therefore, pytype won't spot all type errors. However, some checking is better than no checking.
The type checker adds some seconds to the overall time to run each code cell. You may thus wish to initially turn off the type checking, with %pytype off, and only turn it on after all code is written and tested. You will have to run all cells of your notebook for the type checking to take place.
For a list of all the options for the %pytype command, see the library reference.
%ruff on\n%ruff on
ruff was activated\n
From now on, each cell is automatically linted after it's executed. Here's an example:
In\u00a0[7]: Copied!l = [1, 2, 3]\nif (not 5 in l) == True:\n print(\"5 isn't in the list\")\nl = [1, 2, 3] if (not 5 in l) == True: print(\"5 isn't in the list\")
5 isn't in the list\n
ruff found issues:
lTrue; use if not 5 in l: for truth checks. Suggested fix: Replace with not 5 in l5 with a constant variablenot in. Suggested fix: Convert to not inEvery message indicates the line of the problem.
l can be misread for 1 (one).if (not 5 in l) == True should be simply if 5 not in lEXPECTED_VALUE, instead of literals like 5 that are meaningless to the reader.As this code cell shows, Ruff sometimes suggests how to fix the reported error, but you must consider whether the suggestion is appropriate.
If you don't understand an error message, like the first one, click on the error code in brackets, to get more information from Ruff's website.
Like for type checking, linting one cell at a time means that the linter is unaware of the wider context of your code. For example, in notebooks, variables may be defined in one cell but used in a later cell. As the linter checks each cell separately, it would report an undefined variable in the later cell. We have disabled checks for undefined variables and other checks that would lead to irrelevant error messages in notebooks, which means that genuine undefined variables won't be flagged. But again, some linting is better than none.
If you get errors that you think are irrelevant, you can disable them with the --ignore option: see the library reference.
%allowed on\n%allowed on
allowed was activated\n
Henceforth, after a cell is executed, the allowed linter will list any constructs, modules or built-in types we haven't taught, like this:
from math import pi, sin\n\nprint(f\"\u03c0 is approximately {pi:.5f}.\")\n from math import pi, sin print(f\"\u03c0 is approximately {pi:.5f}.\") \u03c0 is approximately 3.14159.\n
allowed found issues:
We haven't taught the math.sin() function nor f-strings, and allowed reports these.
Any line that ends with the comment # allowed is ignored. This is useful when you don't want the linter to flag a construct that you explain in your essay. For example, adding the comment after print(...) would not report the f-string. Note that the comment makes the tool skip the whole line: if it has several constructs that weren't taught, none of them is reported.
The allowed linter also includes the configuration for TM112, our introductory Computing course, in case you want to use even fewer constructs in your essay. To use that configuration, write %allowed on --config tm112.json. For a list of all the options for the %allowed command, see the library reference.
You can configure the linter with a JSON file that lists the allowed constructs. See the allowed website for instructions.
Deepnote
Rename the allowed.json configuration in the Files section of your project, and adapt it to your course.
def selection_sort(values: list[int]) -> list[int]:\n \"\"\"Return a copy of the values, in ascending order.\"\"\"\n result = values[:]\n for current in range(len(result) - 1):\n # select the smallest element in result[current:] ...\n smallest = current\n for index in range(current + 1, len(result)):\n if result[index] < result[smallest]:\n smallest = index\n # ... and swap it with the current element\n result[current], result[smallest] = result[smallest], result[current]\n return result\ndef selection_sort(values: list[int]) -> list[int]: \"\"\"Return a copy of the values, in ascending order.\"\"\" result = values[:] for current in range(len(result) - 1): # select the smallest element in result[current:] ... smallest = current for index in range(current + 1, len(result)): if result[index] < result[smallest]: smallest = index # ... and swap it with the current element result[current], result[smallest] = result[smallest], result[current] return result In\u00a0[11]: Copied!
def ascending(n: int) -> tuple[list[int]]:\n \"\"\"Return a list of n integers in ascending order.\"\"\"\n return (list(range(1, n + 1)),) # trailing comma to make it a tuple\n\ndef descending(n: int) -> tuple[list[int]]:\n \"\"\"Return a list of n integers in descending order.\"\"\"\n return (list(range(n, 0, -1)),)\ndef ascending(n: int) -> tuple[list[int]]: \"\"\"Return a list of n integers in ascending order.\"\"\" return (list(range(1, n + 1)),) # trailing comma to make it a tuple def descending(n: int) -> tuple[list[int]]: \"\"\"Return a list of n integers in descending order.\"\"\" return (list(range(n, 0, -1)),)
We should of course test these functions, to make sure they produce the expected lists, but we will skip that in this explanation because we're focusing on how to measure run-times.
In\u00a0[12]: Copied!from algoesup import time_cases # allowed\n\ntime_cases(selection_sort, [ascending, descending], start=100, double=4)\nfrom algoesup import time_cases # allowed time_cases(selection_sort, [ascending, descending], start=100, double=4)
Run-times for selection_sort\n\nInput size ascending descending \n 100 200.5 189.1 \u00b5s\n 200 674.9 702.6 \u00b5s\n 400 2925.2 3016.7 \u00b5s\n 800 12291.2 12540.3 \u00b5s\n 1600 47123.4 47894.4 \u00b5s
Running selection sort on lists from 100 to 1600 integers takes about 170 microseconds to 45 milliseconds. To measure precisely such small time spans, function f (here, selection_sort) is called multiple times on the same input, within a loop, and the total time is divided by the number of iterations, to obtain a better estimate of the time taken by a single call to f. The whole process is repeated 3 times, because the run-times will vary due to other processes running on the computer. The lowest of the 3 run-times is reported.
Because function f is called multiple times, it is very important that f does not modify its inputs. For example, if selection_sort sorted the list in-place, instead of returning a new list, then the first call would put the numbers in ascending order, and the subsequent calls would just try to sort an already sorted list, swapping no numbers. We would obtain almost exact same times for ascending and descending input lists, instead of always larger times for descending lists, as shown above.
When executing a code like the previous one, be patient while waiting for the results. Even though each call may just take a few milliseconds or less, the code cell will take several seconds or even minutes to execute, because the function is called many times to make the measurements more robust.
In\u00a0[13]: Copied!from algoesup import time_functions # allowed\n\ntime_functions([selection_sort, sorted], descending, start=100, double=4)\nfrom algoesup import time_functions # allowed time_functions([selection_sort, sorted], descending, start=100, double=4)
Inputs generated by descending\n\nInput size selection_sort sorted \n 100 174.2 0.5 \u00b5s\n 200 664.7 0.8 \u00b5s\n 400 2812.4 1.6 \u00b5s\n 800 11663.4 3.0 \u00b5s\n 1600 45949.8 6.1 \u00b5s
As expected, the built-in sorting implementation is much, much faster.
In\u00a0[14]: Copied!time_cases(sorted, [ascending, descending], 100, 4, text=False, chart=True)\ntime_cases(sorted, [ascending, descending], 100, 4, text=False, chart=True) In\u00a0[15]: Copied!
time_functions([sorted, selection_sort], ascending, 100, 4, chart=True)\ntime_functions([sorted, selection_sort], ascending, 100, 4, chart=True)
Inputs generated by ascending\n\nInput size sorted selection_sort \n 100 489.6 169226.5 ns\n 200 803.1 649820.8 ns\n 400 1510.5 2802905.0 ns\n 800 2902.1 11221960.4 ns\n 1600 5615.1 45070266.6 ns
The 1e7 above the y-axis means that the run-times must be multiplied by 10\u2077, i.e. 10 million.
Note that when calling time_functions([selection_sort, sorted], ...) in the previous section, the run-times were reported in microseconds, but when calling time_functions([sorted, selection_sort], ...) in this section, they were in nanoseconds. The reason is that the library chooses the time unit based on the first run-time measured. If there's a big time difference between the fastest and slowest cases or algorithms, you may wish for the first function in the list to be the slowest one, to report it with small values in a 'large' time unit, instead of very large values in a 'small' time unit. So, in time_functions([f1, f2, ...], case, ...) the slowest function should be f1, and in time_cases(f, [case1, case2, ...], ...) the worst case should be case1.
This document provides guidance on how to write code for your essay.
"},{"location":"coding/#code","title":"Code\u00b6","text":"Your code should be correct, simple, and as readable as possible. Unless the aim of your essay is to discuss advanced Python constructs, try to use only a basic subset of the language. This allows more people, including those with limited knowledge of Python, to understand your code. It also makes your code easier to port to other programming languages.
We recommend the following workflow, which is further explained in the following subsections.
Writing the tests (step 1) before the code they test (step 2) is a cornerstone of test-driven development, a widely used practice. Thinking of the tests early in the process helps you better understand the problem and think of correct solutions.
Info
If you followed our 'getting started' instructions, the software mentioned in the next subsections to carry out the above workflow is already installed.
"},{"location":"coding/#testing","title":"Testing\u00b6","text":"You should write tests for each function, to have some assurance that it is correct. Tests that check the behaviour of a single function are called unit tests. The unit tests should cover normal cases and edge cases: extreme input values and inputs that lead to extreme output values.
For each input, the smallest possible value, e.g. zero or the empty list, is an edge case, and so is the largest possible value, if there is one for that input. If a function is doing a search for an item in a list, then edge cases would be the item being at the start, at the end, or not occurring at all. If the output is a list, then inputs that produce the empty list are edge cases too. In summary, try to think of the 'trickiest' inputs the algorithm has to cope with.
We provide a small library to support algorithmic essays: algoesup. It allows you to easily write and run unit tests. Here's an example. (The # fmt: off and # fmt: on lines will be explained later.)
As the above examples show, your code should contain type hints like x: int and ... -> int to indicate the type of the input and of the output. They make your code easier to understand, and help type checkers detect any type mismatches, like passing a string instead of an integer.
Tip
The mypy type checker provides a handy summary of Python's type hints.
To type check each code cell of your notebook, you must first load an extension included in the algoesup library.
Note
This subsection only applies to Deepnote.
Once you have written, tested and type checked all your code, you should format it so that it follows the Python community's code style. You will need to format each cell, as explained here.
If there's a block of code that you don't want the formatter to change, write # fmt: off on its own line before the block and write # fmt: on after the block, to temporarily switch off formatting for that block. This feature is especially useful for keeping the format of unit test tables, as shown in an earlier example.
The Deepnote formatter automatically enforces simple formatting conventions, like 4 spaces for indentation and 2 empty lines between functions, so you will see fewer warnings in the next stage.
Info
We suspect Deepnote enforces Black's code style.
"},{"location":"coding/#linting","title":"Linting\u00b6","text":"You should lint your code, which means to check it for style violations.
Tip
You may wish to skim at some point the Python code style and docstring conventions.
"},{"location":"coding/#code-style","title":"Code style\u00b6","text":"Our library supports Ruff, the fastest Python linter. To turn it on, write the following after loading the algoesup.magics extension.
Our library also supports the allowed linter, created by ourselves. It checks whether your code only uses a certain subset of the Python language. This gives you some reassurance that your code will be understood by a wide audience.
By default, allowed checks against the Python subset used in our algorithms and data structures course. So, if you're an M269 student, to check that your essay is easily understood by your peers in terms of Python constructs, just add the following after loading the extension:
Complexity analysis gives an indication of how the run-times will grow as the inputs grow, but it can't predict the exact run-times nor which algorithm is in practice fastest.
Our library helps measure and plot the run-times of one function on different kinds of input, or of different functions on the same inputs.
For example, let's suppose our essay is about sorting algorithms and we have implemented selection sort.
"},{"location":"coding/#generating-inputs","title":"Generating inputs\u00b6","text":"To measure the run-times of sorting algorithms on increasingly large lists, we must implement functions that generate such lists. For example, we can write a function that generates lists that are already in ascending order, which is a best case for many sorting algorithms, and a function that generates lists that are in descending order, which is a worst case for some sorting algorithms.
The library expects such input-generating functions to take a non-negative integer n, and to produce a tuple of input values, with total size n. Why a tuple? Although our sorting algorithm takes a single input (a list of integers), many algorithms take more than one input. Thus the input-generating functions must generate a tuple of inputs, in the same order as expected by the algorithm.
"},{"location":"coding/#comparing-cases","title":"Comparing cases\u00b6","text":"To measure the run-times of a function f on best, average and worst case inputs, use library function time_cases(f, [case1, case2, ...], s, d). The second argument can be a list (or tuple) of up to 6 input-generating functions. The time_cases function works as follows.
case1(s) to generate inputs of size s for f.f on the generated inputs and measure its run-time.case2, ....s to double its value and go back to step 1.The whole process stops when s has been doubled d times. If d is zero, the run-times are only measured for size s.
Here's how we could measure the run-times for selection sort on ascending and descending lists. (The algoesup library is not part of allowed's default configuration, so we must explicitly allow importing it.)
Our library also allows you to compare different algorithms for the same input case. For that, use time_functions([f1, f2, ...], case, s, d), which does the following:
case(s) to generate inputs of total size s.f1, f2, etc. on the generated inputs and measure their run-times.s and go to step 1, unless s has been doubled d times.The run-times are measured as for time_cases: take the best of 3 run-times, each obtained by calling the function within a loop and dividing the total time by the number of iterations.
Here's a comparison of the built-in sorted function against selection sort, on descending lists.
If you add argument chart=True to time_cases or time_functions, then you will see a line chart of the run-times, in addition to the exact run-times. If you only want to see the chart, then add arguments text=False, chart=True.
If, as the input size doubles, the run-times...
Looking at the run-times reported in the previous subsections, we can see that sorted is linear because the run-times about double when the input size doubles, whereas selection sort is quadratic because the run-times increase about 4-fold when the input size doubles.
Remember that run-times vary every time you execute a cell because the computer is executing other processes. This may lead to the odd behaviour here and there. For example, we have noted that sorted is occasionally faster for descending lists, which is counter-intuitive because it does have to reverse them.
If you can't see any trend in the run-times, or they aren't what you expect, one possible cause is that the input sizes are too small. Increase start and run again the code cell.
If after increasing the start size several times you still don't get the run-times you expect from your complexity analysis, then there might be other explanations:
For an example of the latter, see the Jewels and Stones essay.
"},{"location":"coding/#final-check","title":"Final check\u00b6","text":"Once you finished your code, check your essay.
"},{"location":"deepnote-background/","title":"Background","text":""},{"location":"deepnote-background/#organisation","title":"Organisation","text":"Deepnote uses an organisational framework with three major parts: workspaces can contain multiple projects and each project can contain multiple notebooks and files.
The workspace is the highest level structure in Deepnote, and is designed to group related Projects and enable team collaboration. Every user can create their own workspaces where they can manage access, set permissions and oversee projects. A workspace can have multiple members each with their own access permissions, but by default they can see all projects in the workspace.
Projects are the next tier down from workspaces in terms of organisation and provide the main working environment as well as the integrated file system. When you duplicated our project, you duplicated all of the notebooks, files and the environment too.
Notebooks are akin to Jupyter notebook. They are interactive documents that combine executable code with richly formatted text and visualisations. Notebooks are where you will write your essays.
"},{"location":"deepnote-background/#deepnote-vs-classic-notebook","title":"Deepnote vs Classic Notebook","text":"Notebooks in Deepnote have similar functionality to classic Jupyter notebooks in that they combine rich text, visualisations and executable code in a single document. But there are a few notable differences in the UI and functionality worth mentioning.
Firstly, Deepnote is a cloud-based Jupyter notebook platform: this means no local software installation is required to get started. It also means you can access your documents from anywhere with an internet connection. This is a double edged sword of course, if you lose your connection you lose access to your notebooks.
In Deepnote the divisions within a notebook are referred to as \u201cblocks\u201d instead of \u201ccells\u201d, but we will continue to use the classic terminology. Deepnote retains the same structure of code and markdown cells as used in Jupyter notebook, but it also provides additional cell types. Besides cells for data science, Deepnote adds rich text cells. Unlike standard Jupyter notebooks, these cells offer a what you see is what you get (WYSIWYG) text editing experience, similar to applications such as MS word and Google Docs. They include spellchecking and the usual formatting shortcuts like Ctrl + B for bold, Ctrl + I for italics, and so on. Rich text cells can be advantageous if you plan to use Deepnote exclusively as they can simplify the writing process. However, it is important to note that any formatting from rich text cells will not be preserved if you download your notebook. So if you plan to use your notebooks on other platforms it is advisable to stick to Markdown cells for writing text.
Finally, there is a key difference in the way Deepnote and Jupyter handle Markdown. Normally to create a line break in Markdown, either a double space followed by the Enter key, or a backslash followed by the Enter key is required. This is the approach followed by Jupyter Notebook and many other notebook interfaces. Deepnote, however, does it differently, simply pressing Enter creates a line break without the need for explicit characters like double space or backslash. This alternative approach is a deviation from the Markdown standard and affects how rendered Markdown looks when moving between platforms.
"},{"location":"deepnote-background/#collaboration","title":"Collaboration","text":"Deepnote was designed with collaboration in mind and offers several features to do this which are not found on some other platforms.
Users in Deepnote can work together on projects simultaneously: any changes made to files and notebooks within the project can be seen instantaneously by both parties. Real time collaboration works best when you are also communicating in real time with your peers, say for example, using Zoom, Teams, Discord or WhatsApp.
Additionally Deepnote offers the option for asynchronous communication through comments. Comments can be left in a specific cell and are visible by anybody viewing the notebook. The first comment made in a cell opens a new thread, and anyone commenting in a thread receives email notifications after a new message is posted. Open threads can be resolved to hide them and save space; threads can be reopened if needed. Any open threads are displayed in a main comments panel on the right-hand side of a project.
Comments are one of the ways to give and receive feedback on your essays. See the feedback guide for more details.
"},{"location":"deepnote-background/#limitations","title":"Limitations","text":"As noted at the start of the guidance, Deepnote was selected as the platform for the Learning Professional Skills with Algorithmic Essays project due to its simple interface, customisable environment, and features for collaborative working. However, it is important to acknowledge and assess its limitations.
As mentioned above, Deepnote deviates from Jupyter Notebook by having new types of cell such as rich text cells. It also handles Markdown in an different way from most other platforms. This has implications for how your notebooks will be rendered using different jupyter interfaces. The same notebook could look different on other platforms compared to Deepnote; the length of text lines might be different and some of the formatting may be altered or lost.
In addition to this, when working on a cloud-based platform such as Deepnote, executing cells can sometimes feel slow, especially when the virtual machine has been idle for a while. Furthermore, an issue has been observed when a Markdown cell contains an excessive amount of text, which appears to slow down performance, potentially due to the autocomplete functionality.
As a final point, the way Deepnote stores notebooks within the environment must be mentioned. You can of course upload a notebook to the system and access it like any other file, but if you want to run the notebook, it must be moved to the NOTEBOOKS section. This then becomes a problem if you wish to access the notebook file again, say using the terminal. When a notebook is moved to this section it effectively takes the notebook out of the integrated file system and locates it to a separate database which the user no longer has access to.
"},{"location":"deepnote-how-to/","title":"Deepnote how-to guides","text":""},{"location":"deepnote-how-to/#account-operations","title":"Account operations","text":""},{"location":"deepnote-how-to/#sign-up-for-deepnote","title":"Sign up for Deepnote","text":"This is explained in our Getting Started guide.
"},{"location":"deepnote-how-to/#log-in","title":"Log in","text":"If you have logged out, to log back in you need to verify your email again:
Before any of the following operations, you must change from project view to workspace view:
You will now see a list of the projects in your workspace: Some projects were automatically added by Deepnote when creating your workspace.
After you completed the desired workspace operations, click in the side panel on the project you want to work next.
"},{"location":"deepnote-how-to/#enable-sharing","title":"Enable sharing","text":"For notebooks, the download operations are called Export as .ipynb and Export as .pdf. If your notebook contains other types of cells besides Markdown and code, the downloaded .ipynb file won\u2019t be rendered correctly on other Jupyter platforms.
This is explained in our Getting Started guide.
"},{"location":"deepnote-how-to/#share-your-project","title":"Share your project","text":"The following assumes you have enabled sharing for your workspace.
The simplest way is to drag the notebook or file from your desktop to the Notebooks or Files section in the side panel.
Alternatively, to upload a file:
To perform an action on a cell, do one of the following:
Running a cell executes the code or formats the Markdown text.
To run one cell, do one of the following:
To run all cells, click Run notebook in the top right corner of the notebook.
Note
The first time you run code, it will take some time, because Deepnote must first start a server with the necessary software.
"},{"location":"deepnote-how-to/#add-a-cell","title":"Add a cell","text":"To insert a cell between two existing cells:
c followed by Enter.m followed by Enter.To append a cell, scroll down to the end of the notebook and do one of the following:
Do one of the following:
Do one of the following:
After typing your comment, press the upwards blue arrow to finish.
Warning
You must be logged into your account to comment on notebooks shared with you. If you\u2019re not logged in, your comments are marked as \u2018anonymous user\u2019 and the essay\u2019s author won\u2019t see them.
"},{"location":"deepnote-how-to/#format-a-code-cell","title":"Format a code cell","text":"This \u2018pretty prints\u2019 the code. Do one of the following:
f in the search box of the menu.)Note
Formatting takes 1-2 seconds and adds an empty line (which you may delete) to the end of the cell.
Warning
If you get a message \u2018parsing failed\u2019, then the code cell is not valid Python and can\u2019t be automatically formatted. This may happen if the cell has IPython commands starting with %.
The workspaces interface provides an overview of any projects in your Workspace. On the left-hand side panel you will find a navigation menu allowing you to quickly navigate to different sections of your workspace. Starting from the top, the sections are:
Integrations - This section allows you to set up and manage connections to data sources. This is mostly used for data science work.
Settings & members - Manage who has access to the workspace and its resources.
A project\u2019s interface has similarities to the interface for your workspace. Starting from the top, the sections on the left-hand side panel are:
Notebooks in Deepnote have the same core functionality as Jupyter Notebooks: they combine executable code and text in the same document.
See Deepnote vs Classic Notebook for some differences between the two.
"},{"location":"deepnote-reference/#access-levels","title":"Access levels","text":"Access levels are the range of permissions or capabilities assigned to a user in Deepnote. They differ between the contexts of workspaces and projects.
The access levels for projects are:
The access levels for workspaces are:
Editor: Editors can create and edit workspace projects.
Admin: Admins have all access rights, including permission to manage workspace members.
Cells (called \u2018blocks\u2019 in Deepnote) are the divisions within each notebook. They are a distinct area where code or text can be added depending on the type of the cell. See our how-to guide for working with cells.
"},{"location":"deepnote-reference/#terminal","title":"Terminal","text":"A terminal will give you a command line interface for your project and runs a bash shell.
Launching a Terminal in Deepnote allows you to run scripts or complete tasks where the GUI is not suitable.
See the Deepnote documentation on terminals for more information.
"},{"location":"deepnote-reference/#environment","title":"Environment","text":"The environment refers to the setup and configuration that supports the execution of code within your project.
The code in each project runs on a virtual machine which is an isolated computing environment with its own CPU memory and storage resources. These specifications can be adjusted in a limited way if required and various software packages can be added to your environment to suit your needs.
When you copied our project, you also copied the environment.
See Deepnote\u2019s documentation on custom environments for more information.
"},{"location":"deepnote-reference/#real-time-collaboration","title":"Real-time collaboration","text":"Real time collaboration refers to the capability of multiple users to work on the same documents in the same project at the same time. Any changes to documents can be seen by all users working on the project as and when they happen.
See Deepnote\u2019s documentation on real-time collaboration for more details.
"},{"location":"deepnote-reference/#asynchronous-collaboration","title":"Asynchronous collaboration","text":"Asynchronous collaboration is a method of working where users do not have to be working at the same time. Users can contribute to projects and documents at their own pace to suit their own schedule.
The main tool for asynchronous collaboration in Deepnote is the comments system. Users can comment on code and text in the corresponding cells to communicate with peers.
"},{"location":"deepnote-reference/#command-palette","title":"Command palette","text":"The command palette provides quick access to all of the files in a project and the most popular actions.
You can open and close the command pallet by pressing Cmd + P on Mac or Ctrl + P on Windows.
"},{"location":"deepnote-reference/#members","title":"Members","text":"A member is a Deepnote user associated with a particular workspace.
When a user is a member of a workspace, they typically have access to all the projects within that workspace, but the access permissions can be adjusted.
Projects do not have members, but you can give or be given access to a project with certain permissions. See Access levels for more information.
"},{"location":"deepnote-reference/#markdown-cheat-sheet","title":"Markdown cheat sheet","text":"Feature Syntax/Example Headers H1 Header# H1 Header H2 Header ## H2 Header H3 Header ### H3 Header H4 Header #### H4 Header H5 Header ##### H5 Header Code Inline Code `Code` Code Block ```Code block``` Formatting Italic _italic_ or *italic* Bold **bold** or __bold__ Strikethrough ~~strikethrough~~ Links External Link [Google](https://www.google.com) Section Link [Top](#top) Lists Bulleted List - List item Numbered List 1. List item Math Inline Math $x=1$ Math Block $$$x=1$$$ Other Quote > Quote Divider --- HTML <h1>Title</h1>"},{"location":"deepnote-reference/#keyboard-shortcuts","title":"Keyboard shortcuts","text":"Deepnote has many keyboard shortcuts for quickly performing typical actions on cells and text.
General
MAC WINDOWS & LINUX ACTION \u2318 + P ctrl + P Show/Hide command paletteBlock Actions
MAC WINDOWS & LINUX ACTION \u21e7 + \u21b5 shift + enter Run current block and move cursor to next block (creates a new cell if at the end of the notebook) \u2318 + \u21b5 ctrl + enter Run current block \u2318 + \u21e7 + . ctrl + shift + . Stop execution \u2318 + \u21e7 + H ctrl + shift + H Hide/Show block output \u2318 + \u21e7 + M ctrl + shift + M Toggle between code and Markdown block \u2318 + \u21e7 + \u232b ctrl + shift + backspace Delete block \u2325 + \u21e7 + \u2191 alt + shift + \u2191 Move block up \u2325 + \u21e7 + \u2193 alt + shift + \u2193 Move block down \u2318 + \u21e7 + D ctrl + shift + D Duplicate block \u2318 + J ctrl + J Add new code block below current one \u2318 + K ctrl + K Add new code block above current one \u2318 + Z ctrl + Z Undo \u2318 + \u21e7 + Z ctrl + shift + Z RedoCode Editing
MAC WINDOWS & LINUX ACTION \u2318 + D ctrl + D Expand selection (multiple cursors) tab tab When caret is at the beginning of a line, add indent; otherwise, show autocomplete suggestions \u21e7 + tab shift + tab Decrease indent \u2318 + / ctrl + / Toggle line/selection comment \u2325 + \u2193 alt + \u2193 Move lines down \u2325 + \u2191 alt + \u2191 Move lines upTerminal
MAC WINDOWS & LINUX ACTION \u2318 + C ctrl + shift + C Copy selected text \u2318 + V ctrl + shift + V Paste"},{"location":"deepnote/","title":"Deepnote","text":"Deepnote is the cloud based Jupyter notebook platform we recommend for writing your essays.
The platform was chosen due to its simple interface, customisable environment, and features for collaborative working.
Warning
This Deepnote guide is limited in scope to the writing, sharing and critiquing of algorithmic essays. There are many features of the platform not covered here. See the official documentation for more extensive coverage.
You may find it helpful to watch the following introduction video.
This guide has three parts:
Note
Use the side panel to navigate the Deepnote guidance.
"},{"location":"example-essays/","title":"Example essays","text":"These examples illustrate different ways of structuring essays and different writing styles.
For some essays, there\u2019s a template that highlights the essay\u2019s structure and the purpose of each section. These templates help you start writing your own essay. Clicking on a button below will open a read-only version of the essay or template.
To get an editable version of a template to start writing your own essay, right-click on a download button. From the pop-up menu, choose \u2018Save file as\u2026\u2019 (or similar) to save the template in a folder of your choice.
Deepnote
You don\u2019t need to download anything because you will have the essay templates and examples once you copied our essay project, as explained in Getting started (Deepnote).
Colab
You don\u2019t need to download any template because you can open them directly, as explained in Getting started (Colab).
"},{"location":"example-essays/#sum-of-1-to-n","title":"Sum of 1 to n","text":"This is a short and simple essay, suitable for those on introductory programming courses. The essay shows two ways of calculating 1 + 2 + \u2026 + n and compares their run-times. The essay follows a simple structure, in which each approach is outlined, implemented and tested before moving on to the next one.
Essay Template Template (download)
"},{"location":"example-essays/#jewels-and-stones","title":"Jewels and Stones","text":"This is a longer essay, for those on data structures and algorithms courses. The problem is to count how many characters of a string occur in another string. The essay solves the problem in three ways, with linear search, a set, and a bag/multiset. The complexity of the three algorithms is analysed and compared to their run-time.
This essay follows a slightly different structure, in which each approach is outlined and its complexity analysed, before deciding which approaches are worth implementing.
Essay Template Template (download)
"},{"location":"example-essays/#two-sum-two-approaches","title":"Two Sum (two approaches)","text":"This classic problem asks to find two numbers in a list that add up exactly to a given number. This essay solves the problem in two ways, with brute-force search (nested loops) and a map (Python dictionary).
Essay
"},{"location":"example-essays/#two-sum-three-approaches","title":"Two Sum (three approaches)","text":"This is an extended version of the previous essay. It adds a third approach, that sorts the list of numbers.
Essay
"},{"location":"feedback/","title":"Feedback guide","text":"Giving feedback on each other\u2019s essays is an important part of developing professional skills with algorithmic essays.
Receiving feedback helps improve your essay, while giving feedback helps develop your communication skills. Moreover, reading other people\u2019s essays is a great way to learn more about Python, algorithms, data structures, code style, etc.
Feedback is part of professional software development practices. Many companies and open source projects have formal code reviews, in which developers must submit their code for inspection by others. Code reviews help increase the quality of the code, share best practices among developers, and on-board new developers.
Many companies use pair programming, in which two developers work together on the same piece of code. While one writes the code, the other reviews it as it\u2019s written, pointing out mistakes and suggesting improvements. The two developers switch roles often during a pair programming session. With Deepnote and Colab, you and someone else can work simultaneously on the same notebook, while using Zoom, Microsoft Teams or some other app to chat.
In summary, by engaging in a feedback process for your and others\u2019 essays, you will develop valuable professional skills.
"},{"location":"feedback/#asking-for-feedback","title":"Asking for feedback","text":"You can ask for feedback at any point during the production of your essay, not just when you have a complete draft. You will have to tell others what kind of feedback you want.
For example, if you\u2019re undecided between three problems, you may write a notebook that just describes the problems and asks others to choose one of them, by including something like:
Please help me choose a problem to tackle. Which of the previous problems would you like to see solved and why?
It helps the reader if the request for feedback stands out from the remaining text. You may prefer to use bold, italics, or HTML to format it differently.
You can also ask for feedback after choosing a problem and thinking of some algorithms, but before investing the time in implementing and testing them. Your request could be:
I\u2019m looking for feedback on the above algorithms. Are they clear? Have I missed other approaches to solving this problem?
Once your notebook is ready for feedback, you need to share it so that others can comment on it. You may invite comments from anyone or only from one or two \u2018essay buddies\u2019: they comment on your essay and you comment on theirs.
Info
For how to share your essay, see the corresponding instructions for Colab, Deepnote or M269.
"},{"location":"feedback/#giving-feedback","title":"Giving feedback","text":"Once you have been invited to comment on an essay, read it as soon as you can, because the author is waiting for it to progress the essay to the next draft.
Feedback should be specific and constructive. Generic comments like \u201cThis is confusing\u201d or \u201cI don\u2019t understand this\u201d aren\u2019t helpful for the author. State what you\u2019re finding hard to grasp, like:
Before adding a comment to a notebook cell, read the existing comments, to avoid repeating the same points others have made.
Comments that aren\u2019t about a specific text paragraph or code cell, but rather about the whole essay, e.g. its structure, should be attached to the first cell, with the essay\u2019s title, or to the last cell.
The author has put effort into their essay, and will appreciate encouraging feedback to keep polishing it. For example, if you commented on a previous version, praise the parts that improved.
"},{"location":"feedback/#acting-on-feedback","title":"Acting on feedback","text":"Deepnote emails every time you get a comment on your essay. You may wish to improve your essay as you get each piece of feedback, or you may wait some time, e.g. a week, to collect a variety of comments and then address them in one pass.
As you scroll down your essay, look for speech bubble icons. Click on them to see the comment thread associated to that cell. Once you modify the cell to address those comments, mark the thread as resolved.
Don\u2019t feel obliged to follow every suggestion you receive. The reviewers of your essay may present contradictory suggestions and some may take too much effort to address.
If you don\u2019t understand a reviewer\u2019s comment, add a comment yourself, asking them for clarification. Be specific, explaining what you don\u2019t understand. Alternatively, rephrase the reviewer\u2019s comment and ask them to confirm your interpretation, e.g. \u201cDo you mean I should rename the variable from \u2026 to \u2026?\u201d
"},{"location":"feedback/#crediting-feedback","title":"Crediting feedback","text":"You should acknowledge who provided input, by adding a section at end of your essay with something like this:
I thank my tutor Jane Doe and my fellow students John Smith and Carla Suarez for feedback that helped improve this essay.
Crediting others allows them to point to your essay to provide evidence, e.g. to prospective employers, of giving feedback others find useful. It\u2019s therefore best if you can be specific about each one\u2019s contribution, in particular if someone provided some of the content, beyond just commenting. Content contributions should be mentioned before feedback. For example:
I thank John Smith for analysing the complexity of the second approach. Jane Doe helped me improve the structure of this essay. Carla Suarez spotted several typos and suggested improvements to the code style.
It\u2019s easiest to keep track of contributions if you update the acknowledgements as you act upon feedback. You may wish to offer co-authorship of the essay to those who made substantial contributions.
The acknowledgments should also mention if your solutions are based on someone else\u2019s, unless you already said so when introducing the algorithms. For example:
The second algorithm was taken from the solution posted by LeetCode user soandso, but the code is my own. The third algorithm and implementation are based on user123\u2019s solution. I thank \u2026
When possible, the acknowledgement text should link directly to the original solutions.
If the code or tests were partly or wholly written by generative AI, say so, preferably indicating the prompts you used.
"},{"location":"getting-started-google-colab/","title":"Getting started (Google Colab)","text":"Follow these steps to start writing essays on Google Colab within a few minutes.
"},{"location":"getting-started-google-colab/#copy-an-essay-template","title":"Copy an essay template","text":"Important
To use Colab, you need a Google account. To create one, visit the Google Account sign in page and follow the instructions.
Info
The first code cell of each template essay notebook installs the necessary software when running the notebook in Colab.
"},{"location":"getting-started-google-colab/#write-the-essay","title":"Write the essay","text":"Now that you have saved and renamed a copy of the template, you can start writing your essay in Colab.
For how to use Jupyter notebooks in Colab, read through the Overview of Colaboratory Features.
For guidance on writing algorithmic essays, see our writing and coding guides.
"},{"location":"getting-started-google-colab/#share-the-essay","title":"Share the essay","text":"When you are ready to share the essay with others, do the following:
For suggestions on how to ask for feedback on your shared essay, see our feedback guide
"},{"location":"getting-started-google-colab/#comment-on-essays","title":"Comment on essays","text":"Once an essay has been shared with you, you can comment on it. See our guide on how to leave feedback.
In Colab, comments are attached to a cell and are displayed next to the cell they refer to.
If you have edit or comment permissions, you can comment on a cell in one of three ways:
You can resolve and reply to comments, and you can target comments to specific collaborators by typing @[email address] (e.g., @user@domain.com). Addressed collaborators will be emailed.
The Comment button in the top-right corner of the page shows all comments attached to the notebook.
"},{"location":"getting-started-m269/","title":"Getting started (M269)","text":"If you\u2019re an M269 student, follow these steps to start writing essays within a few minutes.
"},{"location":"getting-started-m269/#install-software-optional","title":"Install software (optional)","text":"While you can write essays with your current M269 software, we recommend installing two more packages to help you test, check the style, and measure the run-time of code.
m269-23j.(m269-23j) ... and you should be in your M269 folder.To install the software, enter pip install algoesup ruff in the PowerShell / terminal.
Note
You also need the most recent version of allowed, which is available from the Resources tab of the M269 website.
We have created templates to serve as starting points for your essay.
essay-Michael.ipynb) or that indicates the topic (e.g. balanced-brackets.ipynb). If you prefer, you can rename the file later, when you settled on a topic.With the essay template in your M269 folder, you can work on it in the same way you do with the book\u2019s chapters and your TMAs.
m269-23j to activate your M269 environment and go to your M269 folder.nb to open the Jupyter dashboard, from which you can open the essay.For guidance on writing algorithmic essays see our writing and coding guides.
"},{"location":"getting-started-m269/#share-the-essay","title":"Share the essay","text":"Once you have a draft you want others to give feedback on, make a post in the VLE forum corresponding to the topic of your essay, and attach your notebook file.
For example, if your essay is about ordered or unordered collections, post it in the Weeks 1-10 forum, but if it also uses recursion or a sorting algorithm, post it in the Weeks 11\u201320 forum.
Once you have addressed others\u2019 feedback, post the final version of your essay, acknowledging the commenters.
"},{"location":"getting-started-m269/#publish-the-essay-optional","title":"Publish the essay (optional)","text":"If you want to publish your essay outside the M269 forums, you have several options.
algoesup GitHub repository, with a link from the example essays page. The copyright of your essay remains with you.Follow these steps to start writing essays within a few minutes, without any software installation or configuration.
"},{"location":"getting-started/#create-a-deepnote-account","title":"Create a Deepnote account","text":"Check your email for a sign-in link from Deepnote and click it.
Note
There are no passwords for Deepnote when signing up by email. If you explicitly log out of your Deepnote account, see our guide for how to log in.
In Deepnote, answer the introductory questions, which may depend on the type of email you used to sign up.
You should now be looking at an empty notebook that is part of the Welcome to Deepnote project within your workspace. You won\u2019t need that project for writing algorithmic essays, but you may wish to keep it, to later explore Deepnote\u2019s data science features.
For the moment, just proceed with the next steps.
"},{"location":"getting-started/#duplicate-our-project","title":"Duplicate our project","text":"We created an essay project in our Deepnote workspace, to be copied to your workspace. The project has all necessary software pre-installed.
Click Duplicate project to finish the process.
Note
Do not check the box to make your project private: that would prevent sharing your essays later with others.
After a few moments, you will see the project in your workspace, with the name Algorithmic Essays - Duplicate at the top of the screen.
Click on the three dots in the top right corner.
You should now see some notebooks in the left panel.
"},{"location":"getting-started/#copy-a-template","title":"Copy a template","text":"We provide two templates as starting points for your essay. One template is simpler, with introductory programming in mind, the other is for data structures and algorithms courses. To write an essay, copy one of the templates and edit that copy.
This creates a new notebook, with the name of the template followed by \u2018-2\u2019, and opens it.
Once you decided your essay\u2019s topic, you can rename the notebook.
"},{"location":"getting-started/#write-the-essay","title":"Write the essay","text":"Now that you have copied and renamed a template, you can start writing your essay in Deepnote.
If you\u2019re familiar with the classic Jupyter interface, we recommend you first read about the differences with Deepnote.
For a video introduction to notebooks and Deepnote, see our Deepnote guide.
For guidance on writing algorithmic essays, see our writing and coding guides.
Info
If an error occurs in a cell, click on the Show error details box in the bottom right corner of the cell to show the full stack trace.
"},{"location":"getting-started/#share-the-essay","title":"Share the essay","text":"When you are ready to share the essay with others, do the following.
For suggestions on how to ask for feedback on your shared essay, see our feedback guide
"},{"location":"getting-started/#comment-on-essays","title":"Comment on essays","text":"Once an essay has been shared with you, you can comment on it. See our guide on how to leave feedback. If you have comment permissions, do one of the following to make a comment:
After typing your comment, press the upwards blue arrow to finish.
Warning
You must be logged into your account to comment on notebooks shared with you. If you\u2019re not logged in, your comments are marked as \u2018anonymous user\u2019 and the essay\u2019s author won\u2019t see them.
"},{"location":"jn-platform-comparison/","title":"Jupyter Notebook platforms","text":"We have compared 26 Jupyter Notebook (JN) platforms against 11 criteria, to decide which platforms to support. Although we selected criteria that are relevant to our use case, writing and sharing algorithmic essays, we hope they are general enough to be of use by anyone considering the adoption of JN platforms. A comparison table is provided at the bottom of this page.
The datasciencenotebook.org website by Robert Lacok and the awesome-jupyter GitHub repository started by Markus Schanta were invaluable in locating and evaluating many of these platforms.
"},{"location":"jn-platform-comparison/#evaluation-criteria","title":"Evaluation criteria","text":"We used the following criteria to evaluate the platforms:
The following paragraphs briefly note why we have chosen each aspect, and why these features are desirable in educational settings and for writing algorithmic essays.
An important consideration for any platform is whether it is fully compatible with .ipynb files. This file type, used by many platforms, originates from when the platform was called IPython Notebook. The ability to import and export these files removes dependency on a single JN platform, allowing to write an essay in one platform and share it on another.
Being free to use, or having a free account, is a highly desirable feature of any platform. It lowers the barrier to participation for both students and educators, removes extra budget requirements, and can increase the longevity of projects.
The hosting mode (locally or in the cloud) has implications for setup requirements, UI, and collaboration. Cloud-based platforms require the least setup and typically support collaboration and commenting on cells. However, they mostly cater for data scientists in their documentation, and the UI and feature set can change without notice. Access to the underlying notebook files may be restricted, complicating code linting, and interfaces can vary, increasing the learning curve. In contrast, locally installed JN platforms tend to have a familiar and consistent interface, provide unrestricted access to files and have more balanced documentation. However, many lack simple options for collaboration and commenting, and they must be installed and configured by the user.
Any platform suitable for pedagogical practice and particularly writing algorithmic essays must have a customisable run-time environment. It should be adaptable to different course specifications, allowing the use of third-party libraries and tools. Often, the ability to install new Python packages via pip is sufficient, but some platforms go further by allowing environment customisation through a Dockerfile.
Students are often required to share their work with faculty and peers for marking, receiving feedback, and collaboration. If a platform has the option to share notebooks via links with access levels, students can grant recipients permission to read only, leave comments on, or edit the document based on their role. Links can be sent by email to specific individuals or shared with a wider audience on a forum. In some cases, work can be shared without the recipient needing an account on the same platform.
The ability for a JN platform to integrate with other platforms can be highly desirable. For instance, integration with GitHub allows one to leverage version control when developing resources, use a single repository to serve multiple platforms, and back up materials.
The user interface is often the first element of a platform a user encounters. Ease of use, familiarity and which controls are available are all important factors that can help reduce the learning curve. For users already familiar with Jupyter, it\u2019s important to consider whether a platform provides the classic JN interface or a bespoke interface. For the purpose of this comparison, we do not consider Jupyter Lab to have the classic interface.
Some platforms allow real-time collaboration among their users, to work together on documents simultaneously, and see changes instantly. Collaborating this way fosters teamwork and communication skills.
Commenting on cells is useful in many ways. Comments are located close to the relevant code or text, often contained in separate \u201cthreads\u201d where they can be edited, deleted and resolved. This allows other users to provide feedback (and educators to mark) without modifying the existing structure of the notebook.
Having access to a terminal and the underlying file system allows platform users to run custom scripts and manage auxiliary files.
Having access to the underlying notebook files in combination with access to a terminal, allows linters and formatters to be used on these files.
"},{"location":"jn-platform-comparison/#comparison-table","title":"Comparison table","text":"You may need to scroll sideways to see all columns. You can sort the table by clicking on any column header.
Some platforms may no longer exist, or may have changed their name or URL, since we compared them in January 2024.
Platform .ipynb Compatibility Free Account Hosting Customisable Run-time Share via Links GitHub Integration Interface Real-time Collaboration Commenting on Cells Terminal & File System Access Access to Notebook Files Amazon SageMaker Notebooks \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Apache Zeppelin \u2713 \u2713 Local/Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Azure Notebooks \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Carnets (iOS) \u2713 \u2713 Local \u2713 \u2717 \u2717 Classic \u2717 \u2717 \u2713 \u2713 CoCalc \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 CodeOcean \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Count \u2717 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Datalore (JetBrains) \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Deepnote \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2717 Google Colab \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Hyperquery \u2717 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 IBM Watson Studio \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Jupyter Notebook \u2713 \u2713 Local \u2713 \u2717 \u2713 Classic \u2717 \u2717 \u2713 \u2713 JupyterLab \u2713 \u2713 Local \u2713 \u2717 \u2713 Bespoke \u2713 \u2717 \u2713 \u2713 Kaggle Notebooks \u2713 \u2713 Cloud \u2717 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Mode Notebooks \u2717 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Noteable \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 nteract \u2713 \u2713 Local \u2713 \u2717 \u2713 Classic \u2717 \u2717 \u2713 \u2713 Observable \u2717 \u2713 Cloud \u2717 \u2713 \u2717 Bespoke \u2713 \u2713 \u2717 \u2717 Polynote \u2717 \u2713 Local \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 Pluto.jl \u2717 \u2713 Local \u2713 \u2717 \u2717 Bespoke \u2717 \u2717 \u2713 \u2713 Query.me \u2717 \u2717 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717 Quarto \u2713 \u2713 Local \u2713 \u2717 \u2713 Classic \u2717 \u2717 \u2713 \u2713 Saturn Cloud \u2713 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2713 \u2713 VS Code with Jupyter \u2713 \u2713 Local/Cloud \u2713 \u2717 \u2713 Classic/Bespoke \u2713 \u2713 \u2713 \u2713 Zepl \u2717 \u2713 Cloud \u2713 \u2713 \u2713 Bespoke \u2713 \u2713 \u2717 \u2717"},{"location":"library/","title":"Library","text":"The algoesup library provides support for testing, timing and linting code. This documentation is for version 0.3.1.
Simplified testing for Python functions, see the examples.
"},{"location":"library/#algoesup.test.test","title":"test","text":"test(function: Callable, test_table: list) -> None\nTest the function with the test_table. Report failed tests.
Parameters:
Name Type Description Defaultfunction Callable The function to be tested.
requiredtest_table list The list of tests. Each element of test_table is a list or tuple with: a string (the test case name); one or more values (the inputs to the function); the expected output value.
required"},{"location":"library/#timing","title":"Timing","text":"Tools for measuring and plotting run-times, see the examples.
"},{"location":"library/#algoesup.time.time_functions","title":"time_functions","text":"time_functions(\n functions: list[Callable],\n inputs: Callable,\n start: int,\n double: int,\n text: bool = True,\n chart: bool = False,\n value: bool = False,\n) -> None\nPrint or plot the run-times of different functions for the same inputs.
time_functions prints or plots the run-times given list of functions and an input generator. Inputs are generated based on a starting size and are doubled a specified number of times.
Parameters:
Name Type Description Defaultfunctions list[Callable] A list of functions whose run-times will be measured. Must be 1 to 6 functions.
requiredinputs Callable A function to generate inputs when given a specific size.
requiredstart int The starting size for the inputs. Must be positive.
requireddouble int The number of times to double the input size. Must be non-negative.
requiredtext bool If True, print the run-times in text format
True chart bool If True plot the run-times using a chart.
False value bool If True x-axis is labelled \u201cInput value\u201d otherwise \u201cInput size\u201d.
False Raises:
Type DescriptionAssertionError If input conditions are not satisfied.
"},{"location":"library/#algoesup.time.time_cases","title":"time_cases","text":"time_cases(\n function: Callable,\n cases: list[Callable],\n start: int,\n double: int,\n text: bool = True,\n chart: bool = False,\n) -> None\nPrint or plot the run-times of function for different input cases.
time_cases prints or plots the run-times of a single function using a list of different input generators. Inputs are generated based on a starting size and are doubled a specified number of times.
Parameters:
Name Type Description Defaultfunction Callable A function whose run-times will be measured.
requiredcases list[Callable] A list of 1 to 6 functions to generate inputs of different cases, e.g. best-, normal- and worst-case.
requiredstart int The starting size for the inputs. Must be positive.
requireddouble int The number of times to double the input size. Must be non-negative.
requiredtext bool If True, print the run-times in text format.
True chart bool If True, plot the run-times using a chart.
False Raises:
Type DescriptionAssertionError If input conditions are not satisfied.
"},{"location":"library/#algoesup.time.time_functions_int","title":"time_functions_int","text":"time_functions_int(\n functions: list[Callable],\n generator: Callable = int_value,\n start: int = 1,\n double: int = 10,\n text: bool = True,\n chart: bool = True,\n) -> None\nTime functions that take a single integer as input.
time_functions_int uses time_functions to measure and display the run-times of a given list of functions that accept a single integer input. The integer inputs are generated starting from a specified value that defaults to 1, and are doubled a specified number of times that defaults to 10.
Parameters:
Name Type Description Defaultfunctions list[Callable] A list of functions whose run-times will be measured. Each function must accept a single integer argument. Must be 1 to 6 functions.
requiredgenerator Callable A function to generate integer inputs. Defaults to int_value, which returns a tuple containing the input integer.
int_value start int The starting integer value for inputs. Defaults to 1. Must be positive.
1 double int The number of times to double the input integer value. Defaults to 10. Must be non-negative.
10 text bool If True, print the run-times in text format.
True chart bool If True, plot the run-times using a chart.
True"},{"location":"library/#linting","title":"Linting","text":"Linting tools for Jupyter Notebook environments.
See the type checking and linting examples.
"},{"location":"library/#algoesup.magics.allowed","title":"allowed","text":"allowed\nActivate/deactivate the allowed linter.
When active, the linter checks each code cell that is executed for any Python constructs that are not listed in the given configuration file.
%allowed on ... activates the linter with any command options given after on%allowed on is equal to %allowed on --config m269.json%allowed off deactivates the linter%allowed shows the current status of the linter%allowed? shows this documentation and the command\u2019s optionsFor a list of possible options ..., enter !allowed -h in a code cell. Some options may not be appropriate when running allowed within a notebook.
The --config option expects m269.json, tm112.json or the name of a JSON file with your own configuration.
pytype\nActivate/deactivate the pytype linter.
When active, the linter checks each code cell that is executed for type errors.
%pytype on ... activates the linter with the command options given after on%pytype on is equal to %pytype on --disable name-error,import-error%pytype off deactivates the linter%pytype shows the current status of the linter%pytype? shows this documentation and the command\u2019s optionsFor a list of possible options ..., enter !pytype -h in a code cell. Some options may not be appropriate when running pytype within a notebook.
The --disable option expects a list of errors to ignore, without spaces. By default, %pylint ignores these errors:
ruff\nActivate/deactivate the Ruff linter.
When active, the linter checks each code cell that is executed against the selected code style rules.
%ruff on ... activates the linter with any command options given after on (see [ruff\u2019s list of rules])%ruff on is equal to %ruff on --select A,B,C90,D,E,W,F,N,PL --ignore D100,W292,F401,F821,D203,D213,D415%ruff off deactivates the linter%ruff shows the current status of the linter%ruff? shows this documentationThe command %ruff on ... will run ruff check --output-format json ... on each cell. For a list of the possible options ..., enter !ruff help check in a code cell. Some options may not be appropriate when running Ruff within a notebook.
The --select and --ignore options expect a list of rule codes, without spaces.
By default, %ruff enables the rules from flake8-builtins (A), flake8-bugbear (B), mccabe (C90), pydocstyle (D), pycodestyle (E, W), pyflakes (F), pep8-naming (N), and pylint (PL).
By default, %ruff ignores these rules:
This document provides guidance on how to produce your essay.
Warning
Although we wish to accommodate novice programmers in the future, the guide currently has data structures and algorithms students in mind.
An essay can have more than one author, although more than two is harder to manage. Deepnote and Colab make it easy to work collaboratively on a single notebook, at the same time or asynchronously, and leave comments to co-authors. You may wish to first pitch your essay idea to your peers, to recruit co-authors.
In the rest of this guide, \u2018you\u2019 and \u2018your\u2019 are both singular and plural pronouns, to refer simultaneously to a single author or multiple authors.
Tip
You may wish to keep this guide open while going through your copy of our template.
"},{"location":"writing/#problem","title":"Problem","text":"It\u2019s worth spending time on choosing an appropriate problem before putting effort into an essay about it. You may invent your own problem or select an existing one. For example, it may be a non-assessed exercise from your course, or it may relate to your hobby or work. If so, provide any information the reader needs to understand the problem. If the problem is from your work, get permission from your employer or client.
There are many websites with thousands of algorithmic problems to choose from. We have used Kattis and LeetCode in the past.
Some sites, like LeetCode, tag their problems with the data structure or algorithmic technique needed, like \u2018array\u2019 or \u2018sorting\u2019. This helps you find problems about a particular topic.
Some sites, like LeetCode, have official and user-provided solutions, but the latter may be terse (single-letter identifiers, no comments) or not fully analysed. Other sites, like the International Olympiad in Informatics, often have just solution hints or outlines. You may thus wish to write an essay that fully implements a solution outline or that improves and compares several user solutions. Either way would be useful to the user community of those sites.
It is often said that the best way to learn a topic is to have to explain it to others. You may thus wish to pick a problem on a topic you\u2019re not comfortable with, choose two existing solutions, and explain them in an essay.
If you\u2019re undecided, make a shortlist of 2\u20133 problems and ask your peers for their opinion.
"},{"location":"writing/#text","title":"Text","text":"An essay presents two or more algorithmic solutions for a computational problem, and concludes which one is better, according to some criteria. Possible criteria include:
The essay should thus have a clear narrative, going from the problem to the conclusion.
An algorithmic essay contains more text than code, and while code can and should have comments, the text carries most of the explanation. It\u2019s thus important for the text to be clear and error-free.
Essays can be written in any style: it\u2019s a personal choice. For example, you can use \u2018we\u2019, \u2018I\u2019 or an impersonal form.
Tip
Strunk and White\u2019s The Elements of Style is a classic. The examples are dated but the advice is good.
Deepnote
Notebooks can have rich-text cells (headings, paragraph, bullet item, etc.) that, contrary to the Markdown cells, are spell-checked as you write the text and support keyboard shortcuts, like Ctrl + B to put the selected text in bold. Unless you want to keep your essays in Deepnote, we do not recommend using rich-text cells, as their formatting is lost when downloading the notebook to your computer.
"},{"location":"writing/#structure","title":"Structure","text":"An essay starts with a title that states the problem or the algorithmic technique to be used. Next, put your name(s) and the current date, which should be updated whenever you edit the essay.
Next, without any heading, comes the introduction. It should state what the essay is about. Normally an essay\u2019s aim is to solve a particular problem, but it may also illustrate a general technique, like space-time trade-offs or recursion, or highlight an issue, like the difference between complexity analysis and run-time performance.
The introduction should also state what you assume the reader to know, as no essay can explain everything from first principles. For example, tell the reader that they must know about binary trees to understand your essay.
Following the introduction, use section headings to structure your essay, for example:
The algorithms and implementations sections may have subsections, one per algorithm.
An alternative structure implements each approach before evaluating all of them:
If the problem description is a single paragraph, you may include it in the introduction, rather than having a separate section. If you didn\u2019t invent the problem, indicate its source, e.g. by providing a link to a website or by writing something like \u201cThis is problem 4.5 in [book title] by [author].\u201d
"},{"location":"writing/#algorithms","title":"Algorithms","text":"You should choose at least two sufficiently different algorithms that solve the problem, and describe each one succinctly, preferably before implementing it, to make the code easier to understand for the reader.
We recommend to not describe algorithms that are only slight variants of each other, as this is usually of little interest, and to only include two algorithms in your first draft.
If you\u2019re using solutions by others, e.g. by LeetCode users, acknowledge the original author and provide a link to their solution. If you have modified their solutions, state what you have changed and explain why.
You should include worst-case complexity analyses of the various solutions you propose, as this helps discard the inefficient ones that may not be worth implementing.
"},{"location":"writing/#code","title":"Code","text":"See our coding guide.
"},{"location":"writing/#final-check","title":"Final check","text":"Whether it\u2019s your essay\u2019s first draft or final version, before you share it with others, you should restart the kernel and run all cells, so that you have a \u2018clean\u2019 version. Then, after a break, read your essay with \u2018fresh eyes\u2019 from start to end and fix any typos or missing explanations you find.
Look at the table of contents of your notebook and check that your section headings are at the right level.
Deepnote
The table of contents is on the left sidebar.
Colab
To see the table of contents, click the bullet list icon in the left sidebar.
Finally, let others comment on your essay and help you produce a better version. See our feedback guide for details.
"},{"location":"essays/example-1-to-n/","title":"Sum of 1 to n","text":"This short notebook provides a very simple example of an algorithmic essay and shows the support that our library provides.
The problem to be solved is to compute the sum of the integers, 1, 2, ..., n, for some given n. Two solutions will be presented, both only using basic Python.
The first thing to do is to import the necessary functions from the algorithmic essays support library. The functions will be explained later, when they're used.
In\u00a0[1]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff In\u00a0[2]: Copied!
# import functions to test the code and to measure the execution time\nfrom algoesup import test, time_functions_int\n# import functions to test the code and to measure the execution time from algoesup import test, time_functions_int
The library also includes two commands to turn on the tools that will check the code as it's executed. There won't be any messages in this notebook because the code passes all checks.
In\u00a0[3]: Copied!%load_ext algoesup.magics\n# check the code for style violations\n%ruff on\n# check that only the subset of Python taught in our introductory course TM112 is used\n%allowed on --config tm112.json\n%load_ext algoesup.magics # check the code for style violations %ruff on # check that only the subset of Python taught in our introductory course TM112 is used %allowed on --config tm112.json
ruff was activated\nallowed was activated\nIn\u00a0[4]: Copied!
tests = [\n # case n, sum\n [\"no integers\", -1, 0],\n [\"one integer\", 1, 1],\n [\"n is even\", 4, 10], # 1 + 2 + 3 + 4 = 10\n [\"n is odd\", 7, 28], # 1 + 2 + 3 + 4 + 5 + 6 + 7 = 28\n]\ntests = [ # case n, sum [\"no integers\", -1, 0], [\"one integer\", 1, 1], [\"n is even\", 4, 10], # 1 + 2 + 3 + 4 = 10 [\"n is odd\", 7, 28], # 1 + 2 + 3 + 4 + 5 + 6 + 7 = 28 ] In\u00a0[5]: Copied!
def sum_with_loop(n):\n \"\"\"Return 1 + 2 + ... + n, using a loop.\"\"\"\n total = 0\n for number in range(1, n + 1):\n total = total + number\n return total\ndef sum_with_loop(n): \"\"\"Return 1 + 2 + ... + n, using a loop.\"\"\" total = 0 for number in range(1, n + 1): total = total + number return total
The next step is to check the code with the imported test function, which takes two arguments: the function to be tested and a test table. Every test case in the test table is checked and if the actual output isn't the expected output, the test is reported as having failed.
test(sum_with_loop, tests)\ntest(sum_with_loop, tests)
Testing sum_with_loop...\nTests finished: 4 passed, 0 failed.\n
Algorithm 1 passes all tests. Since the algorithm does exactly what the problem asks for, the only test that could fail is for n < 1. However, in that case the loop is skipped and the returned total is zero, as desired.
In\u00a0[7]: Copied!def sum_with_formula(n):\n \"\"\"Return 1 + 2 + ... + n, using a formula.\"\"\"\n return n * (n + 1) // 2\ndef sum_with_formula(n): \"\"\"Return 1 + 2 + ... + n, using a formula.\"\"\" return n * (n + 1) // 2
This function is solving the same problem as the previous one, so it must be tested with the exact same tests.
In\u00a0[8]: Copied!test(sum_with_formula, tests)\ntest(sum_with_formula, tests)
Testing sum_with_formula...\nTests finished: 4 passed, 0 failed.\n
The code passes the tests, and yet the algorithm is wrong! The formula is only meant for n \u2265 1. It just happens that if n = 0 or n = -1 then n \u00b7 (n+1) / 2 = 0, as desired, but for n < -1 the result is non-zero. An additional test helps confirm this.
In\u00a0[9]: Copied!tests.append([\"n < -1\", -5, 0]) # testing with n = -5\n\ntest(sum_with_formula, tests)\ntests.append([\"n < -1\", -5, 0]) # testing with n = -5 test(sum_with_formula, tests)
Testing sum_with_formula...\nn < -1 FAILED: 10 instead of 0\nTests finished: 4 passed, 1 failed.\n
The result is -5 \u00b7 (\u20135 + 1) / 2 = -5 \u00b7 -4 / 2 = 10 instead of zero. The algorithm must be modified.
Algorithm 2 (corrected): If n < 1, return 0, otherwise return n \u00b7 (n+1) / 2.
In\u00a0[10]: Copied!def sum_with_formula(n):\n \"\"\"Return 1 + 2 + ... + n, using a formula.\"\"\"\n if n < 1:\n return 0\n else:\n return n * (n + 1) // 2\n\ntest(sum_with_formula, tests)\ndef sum_with_formula(n): \"\"\"Return 1 + 2 + ... + n, using a formula.\"\"\" if n < 1: return 0 else: return n * (n + 1) // 2 test(sum_with_formula, tests)
Testing sum_with_formula...\nTests finished: 5 passed, 0 failed.\n
Now the additional test also passes.
As a new test was added, the first algorithm must be tested again.
In\u00a0[11]: Copied!test(sum_with_loop, tests)\ntest(sum_with_loop, tests)
Testing sum_with_loop...\nTests finished: 5 passed, 0 failed.\nIn\u00a0[12]: Copied!
time_functions_int([sum_with_loop, sum_with_formula])\ntime_functions_int([sum_with_loop, sum_with_formula])
Inputs generated by int_value\n\nInput value sum_with_loop sum_with_formul \n 1 152.7 88.2 ns\n 2 175.8 88.5 ns\n 4 207.0 88.6 ns\n 8 276.6 88.3 ns\n 16 401.7 95.0 ns\n 32 705.5 99.5 ns\n 64 1388.1 99.6 ns\n 128 2650.9 99.7 ns\n 256 5189.3 103.1 ns\n 512 11156.8 103.0 ns\n 1024 23184.4 104.4 ns
Computing the sum with the formula always takes about the same time, around 90 to 100 nanoseconds (that's what the 'ns' means). However, the run-times for the sum with the loop grow as n gets larger. If the value of n doubles, the number of iterations also doubles, so the run-time also roughly doubles, as can be seen above the chart. As n increases, the iterative sum gets slower and slower. At n = 1024, using a loop is about 200 times slower than using the formula!
"},{"location":"essays/example-1-to-n/#sum-of-1-to-n","title":"Sum of 1 to n\u00b6","text":"Michel Wermelinger, 22 January 2024, last updated 16 March 2024
"},{"location":"essays/example-1-to-n/#tests","title":"Tests\u00b6","text":"Before thinking of a solution, it's best to write down some tests, as they help our understanding of the problem. Each test is the input integer n and the corresponding expected integer output 1 + 2 + ... + n.
The tests should include edge cases: inputs that are extreme values or that lead to extreme outputs. For this problem, edge cases are when there are no integers to add up (n < 1) or when there's only one (n = 1).
Tests should also include normal cases. When the input is an integer, tests typically include odd and even values.
The test function that was imported in the previous cell expects the tests to be written as a table, e.g. as a list of lists. The table must have one row per test case. Each row has a column with a string describing the case, one column per input, and a final column with the expected output.
The next step is to think of possible algorithms that solve the problem.
"},{"location":"essays/example-1-to-n/#using-a-loop","title":"Using a loop\u00b6","text":"The probably most obvious algorithm is to explicitly calculate the sum, by iterating over the integers from 1 to n.
Algorithm 1: Set the total to zero. For each value from 1 to n, add the value to the total. Return the total.
The algorithm is implemented as follows.
"},{"location":"essays/example-1-to-n/#using-a-formula","title":"Using a formula\u00b6","text":"It's possible to compute the sum directly, using a well-known formula, taught in many introductory math courses:
1 + 2 + 3 + ... + (n - 2) + (n - 1) + n = (1 + n) + (2 + n - 1) + (3 + n - 2) + ... = (n + 1) \u00b7 n / 2.
The formula is based on 'pairing up' the first with the last number, the second with the next to last, and so on. Each pair adds up to n + 1, and the number of pairs is half of n. The algorithm is simply the formula:
Algorithm 2: Return n \u00b7 (n+1) / 2.
"},{"location":"essays/example-1-to-n/#performance","title":"Performance\u00b6","text":"The final, optional, step is to compare the performance of both solutions to see which is fastest. For this problem, the second algorithm is expected to be faster that the first one, as it computes the sum directly, without iterating over n integers.
The time_functions_int function, which was imported in the first cell, takes a list of functions that have a single integer n as input, and measures their run-times for n = 1, 2, 4, 8, ..., 1024. Doubling the input allows to see any trends in how run-times grow with just eleven executions of the two functions. Running the functions with n = 1, 2, 3, 4, 5, ..., 1024 would take much longer and not produce any additional insight.
This essay presented two solutions to a simple problem: computing the sum 1 + ... + n, for any integer n. The sum should be zero if n < 1.
The first solution computes the sum iteratively, while the second computes it directly, with a formula. The second is always faster, even for n = 1. Moreover, as n increases, the first approach becomes slower whereas the second always takes about the same time.
This essay illustrates the need for thinking about different algorithms for the same problem, as one approach may be much more efficient than others.
The essay also showed that passing all tests doesn't mean that the code is correct. As the various algorithms are developed, new tests may have to be added.
"},{"location":"essays/example-jewels/","title":"Jewels and Stones","text":"In this example algorithmic essay I will tackle LeetCode problem Jewels and Stones. The inputs are two strings jewels and stones, where each character represents a type of stone, e.g. A for amethyst, D for diamond, b for basalt and ? for an unknown stone. The jewels string contains the characters that represent jewels, without repetition. The desired output is the number of stones that are jewels. For example, if jewels is \"AD\" and stones is \"b?AbDAb\" then the output is 3 because three of the stones are jewels (two amethysts and one diamond). To be clear, which stones and jewels the characters represent doesn't really matter: the output is simply how many characters of the second string occur in the first string.
This essay will illustrate a space-time trade-off: by using an additional data structure, we get a faster algorithm. I assume you're familiar with sets, bags (multisets) and basic complexity analysis. This essay uses Big-Theta notation \u0398(...), but if you're not familiar with it, you can read it as Big-Oh notation O(...) for the purposes of the analyses done below. Sorting, binary search, and log-linear and logarithmic complexities are mentioned in Section 2.3, but you can skip it, as it won't affect the understanding of the rest of the essay.
Before starting to solve the problem, I import the necessary functions from algoesup, the algorithmic essays support library, and turn on the tools that will check my code for style and type violations (with Ruff and pytype), and for constructs I didn't teach (with allowed).
import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff pytype\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff pytype In\u00a0[2]: Copied!
from algoesup import test, time_cases, time_functions\nfrom algoesup import test, time_cases, time_functions In\u00a0[3]: Copied!
%load_ext algoesup.magics\n%ruff on\n%pytype on\n%allowed on\n%load_ext algoesup.magics %ruff on %pytype on %allowed on
ruff was activated\npytype was activated\nallowed was activated\nIn\u00a0[4]: Copied!
# don't allow code formatters to change this table\n# fmt: off\ntests = [\n # case jewels stones output\n (\"no jewels\", \"\", \"abc\", 0),\n (\"no stones\", \"DA\", \"\", 0),\n (\"both empty\", \"\", \"\", 0),\n (\"none is a jewel\", \"DA\", \"dada?\", 0),\n (\"equal strings\", \"DA\", \"DA\", 2),\n (\"all same jewel\", \"DA\", \"AAAA\", 4),\n (\"some jewels missing\", \"DARJ\", \"RRD\", 3),\n (\"some not jewels\", \"RAD\", \"bRADAb\", 4),\n]\n# allow code formatters to change the following cells\n# fmt: on\n# don't allow code formatters to change this table # fmt: off tests = [ # case jewels stones output (\"no jewels\", \"\", \"abc\", 0), (\"no stones\", \"DA\", \"\", 0), (\"both empty\", \"\", \"\", 0), (\"none is a jewel\", \"DA\", \"dada?\", 0), (\"equal strings\", \"DA\", \"DA\", 2), (\"all same jewel\", \"DA\", \"AAAA\", 4), (\"some jewels missing\", \"DARJ\", \"RRD\", 3), (\"some not jewels\", \"RAD\", \"bRADAb\", 4), ] # allow code formatters to change the following cells # fmt: on In\u00a0[5]: Copied!
def count_in_string(jewels: str, stones: str) -> int:\n \"\"\"Return the number of characters in `stones` that are in `jewels`.\n\n Use Algorithm 2: for each stone, check if it's a jewel.\n Complexity: best \u0398(len(stones)); worst \u0398(len(stones) * len(jewels))\n \"\"\"\n counter = 0\n for stone in stones:\n if stone in jewels:\n counter = counter + 1\n return counter\n\n\n# test(function, test_table) runs `function` on each test in `test_table`\n# and prints the tests that fail (actual output isn't the expected output).\ntest(count_in_string, tests)\ndef count_in_string(jewels: str, stones: str) -> int: \"\"\"Return the number of characters in `stones` that are in `jewels`. Use Algorithm 2: for each stone, check if it's a jewel. Complexity: best \u0398(len(stones)); worst \u0398(len(stones) * len(jewels)) \"\"\" counter = 0 for stone in stones: if stone in jewels: counter = counter + 1 return counter # test(function, test_table) runs `function` on each test in `test_table` # and prints the tests that fail (actual output isn't the expected output). test(count_in_string, tests)
Testing count_in_string...\nTests finished: 8 passed, 0 failed.\n
The implementation of Algorithm 2 passes all tests. Next, Algorithm 3 can be implemented with Python's Counter class.
from collections import Counter\n\n\ndef count_in_bag(jewels: str, stones: str) -> int:\n \"\"\"Return the number of characters in `stones` that are in `jewels`.\n\n Use Algorithm 3: put stones in a bag; add the frequencies of those that are jewels.\n Complexity: \u0398(len(stones) + len(jewels))\n \"\"\"\n bag = Counter(stones)\n counter = 0\n for jewel in jewels:\n counter = counter + bag[jewel]\n return counter\n\n\ntest(count_in_bag, tests)\nfrom collections import Counter def count_in_bag(jewels: str, stones: str) -> int: \"\"\"Return the number of characters in `stones` that are in `jewels`. Use Algorithm 3: put stones in a bag; add the frequencies of those that are jewels. Complexity: \u0398(len(stones) + len(jewels)) \"\"\" bag = Counter(stones) counter = 0 for jewel in jewels: counter = counter + bag[jewel] return counter test(count_in_bag, tests)
Testing count_in_bag...\nTests finished: 8 passed, 0 failed.\n
Finally, Algorithm 4 can be implemented with Python's built-in set type.
def count_in_set(jewels: str, stones: str) -> int:\n \"\"\"Return the number of characters in `stones` that are in `jewels`.\n\n Use Algorithm 4: put jewels in a set; count the stones that are in the set.\n Complexity: \u0398(len(jewels) + len(stones))\n \"\"\"\n jewel_set = set(jewels)\n counter = 0\n for stone in stones:\n if stone in jewel_set:\n counter = counter + 1\n return counter\n\n\ntest(count_in_set, tests)\ndef count_in_set(jewels: str, stones: str) -> int: \"\"\"Return the number of characters in `stones` that are in `jewels`. Use Algorithm 4: put jewels in a set; count the stones that are in the set. Complexity: \u0398(len(jewels) + len(stones)) \"\"\" jewel_set = set(jewels) counter = 0 for stone in stones: if stone in jewel_set: counter = counter + 1 return counter test(count_in_set, tests)
Testing count_in_set...\nTests finished: 8 passed, 0 failed.\nIn\u00a0[8]: Copied!
def best_case(size: int) -> tuple[str, str]:\n \"\"\"Return a best-case input (pair of strings) of the given size.\n\n Output: (jewels, stones) with\n - len(jewels) + len(stones) == size, with each string half the size\n - jewels has no duplicate characters\n - all stones are jewels[0]\n \"\"\"\n j = size // 2\n s = size - j\n # create a string with j different characters (Unicode 32 onwards)\n jewels = \"\"\n for code in range(32, 32 + j):\n jewels = jewels + chr(code)\n # create a string with s spaces (Unicode 32), the first character in jewels\n stones = \" \" * s\n return (jewels, stones)\ndef best_case(size: int) -> tuple[str, str]: \"\"\"Return a best-case input (pair of strings) of the given size. Output: (jewels, stones) with - len(jewels) + len(stones) == size, with each string half the size - jewels has no duplicate characters - all stones are jewels[0] \"\"\" j = size // 2 s = size - j # create a string with j different characters (Unicode 32 onwards) jewels = \"\" for code in range(32, 32 + j): jewels = jewels + chr(code) # create a string with s spaces (Unicode 32), the first character in jewels stones = \" \" * s return (jewels, stones)
allowed found issues:
Note that the allowed tool reports that I haven't taught my students the chr function. That's why I explained it before presenting the code.
Moving on, I write some tests, to check that best_case is generating the right strings.
# fmt: off\ntest(best_case, [\n # case, size, (jewels, stones)\n (\"empty strings\", 0, (\"\", \"\")),\n (\"no jewels\", 1, (\"\", \" \")),\n (\"odd size\", 5, (' !', \" \")),\n])\n# fmt: on\n # fmt: off test(best_case, [ # case, size, (jewels, stones) (\"empty strings\", 0, (\"\", \"\")), (\"no jewels\", 1, (\"\", \" \")), (\"odd size\", 5, (' !', \" \")), ]) # fmt: on Testing best_case...\nTests finished: 3 passed, 0 failed.\n
To generate a worst case, I have two options: no stone is a jewel or all stones are the last jewel (Unicode 31 + j). I choose the first one. (Spoiler alert: I made the wrong choice. Can you see why?)
In\u00a0[10]: Copied!def worst_case(size: int) -> tuple[str, str]:\n \"\"\"Return a worst-case input (pair of strings) of the given size.\n\n Output: (jewels, stones) with\n - len(jewels) + len(stones) == size, with each string half the size\n - jewels has no duplicate characters\n - no stone is a jewel\n \"\"\"\n j = size // 2\n s = size - j\n # create a string with j different characters (Unicode 32 onwards)\n jewels = \"\"\n for code in range(32, 32 + j):\n jewels = jewels + chr(code) # allowed\n # create a string with s different characters (Unicode 32+j onwards)\n stones = \"\"\n for code in range(32 + j, 32 + j + s):\n stones = stones + chr(code) # allowed\n return (jewels, stones)\n\n\n# fmt: off\ntest(worst_case, [\n # case, size, (jewels, stones)\n (\"empty strings\", 0, (\"\", \"\")),\n (\"no jewels\", 1, (\"\", \" \")),\n (\"odd size\", 11, (' !\"#$', \"%&'()*\")), # 5 jewels, 6 stones\n])\n# fmt: on\n def worst_case(size: int) -> tuple[str, str]: \"\"\"Return a worst-case input (pair of strings) of the given size. Output: (jewels, stones) with - len(jewels) + len(stones) == size, with each string half the size - jewels has no duplicate characters - no stone is a jewel \"\"\" j = size // 2 s = size - j # create a string with j different characters (Unicode 32 onwards) jewels = \"\" for code in range(32, 32 + j): jewels = jewels + chr(code) # allowed # create a string with s different characters (Unicode 32+j onwards) stones = \"\" for code in range(32 + j, 32 + j + s): stones = stones + chr(code) # allowed return (jewels, stones) # fmt: off test(worst_case, [ # case, size, (jewels, stones) (\"empty strings\", 0, (\"\", \"\")), (\"no jewels\", 1, (\"\", \" \")), (\"odd size\", 11, (' !\"#$', \"%&'()*\")), # 5 jewels, 6 stones ]) # fmt: on Testing worst_case...\nTests finished: 3 passed, 0 failed.\n
The # allowed comment in lines 14 and 18 tells the tool that chr() is allowed, because it was explained, and hence should not be reported.
Finally I generate random typical cases in which not all stones are jewels and not all jewels occur in the stones.
In\u00a0[11]: Copied!import random\n\n\ndef normal_case(size: int) -> tuple[str, str]:\n \"\"\"Return a typical input (pair of strings) of the given size.\n\n Output: (jewels, stones) with\n - len(jewels) + len(stones) == size, with each string half the size\n - jewels has no duplicate characters\n - stones has some jewels and some non-jewels, if len(jewels) > 1\n - not all jewels occur in stones, if len(jewels) > 1\n \"\"\"\n j = size // 2\n s = size - j\n # create a string with j different characters (Unicode 32 onwards)\n jewels = \"\"\n for code in range(32, 32 + j):\n jewels = jewels + chr(code) # allowed\n # create a string with s random characters from Unicode 33 to 33 + 2j\n stones = \"\"\n for _ in range(s):\n stones = stones + chr(random.randint(33, 33 + 2 * j)) # allowed\n return (jewels, stones)\n\n\n# Can't test with a test table, because the output is random.\n(jewels, stones) = normal_case(20)\ncounter = count_in_string(jewels, stones)\nprint(\"Some stones are jewels:\", counter > 0)\nprint(\"Some stones aren't jewels:\", counter < len(stones))\nimport random def normal_case(size: int) -> tuple[str, str]: \"\"\"Return a typical input (pair of strings) of the given size. Output: (jewels, stones) with - len(jewels) + len(stones) == size, with each string half the size - jewels has no duplicate characters - stones has some jewels and some non-jewels, if len(jewels) > 1 - not all jewels occur in stones, if len(jewels) > 1 \"\"\" j = size // 2 s = size - j # create a string with j different characters (Unicode 32 onwards) jewels = \"\" for code in range(32, 32 + j): jewels = jewels + chr(code) # allowed # create a string with s random characters from Unicode 33 to 33 + 2j stones = \"\" for _ in range(s): stones = stones + chr(random.randint(33, 33 + 2 * j)) # allowed return (jewels, stones) # Can't test with a test table, because the output is random. (jewels, stones) = normal_case(20) counter = count_in_string(jewels, stones) print(\"Some stones are jewels:\", counter > 0) print(\"Some stones aren't jewels:\", counter < len(stones))
Some stones are jewels: True\nSome stones aren't jewels: True\n
The loop variable's name is just an underscore (line 21) to avoid a warning that the loop variable isn't used in the loop's body.
In\u00a0[12]: Copied!cases = [best_case, normal_case, worst_case]\ntime_cases(count_in_string, cases, start=10, double=4)\ncases = [best_case, normal_case, worst_case] time_cases(count_in_string, cases, start=10, double=4)
Run-times for count_in_string\n\nInput size best_case normal_case worst_case \n 10 202.6 198.2 155.0 ns\n 20 337.8 324.3 299.8 ns\n 40 596.3 550.1 425.1 ns\n 80 1088.7 1043.6 796.5 ns\n 160 2071.6 2272.3 1558.1 ns
The results are baffling: the worst case is the fastest!
The linear search is done with the in operator, which is much faster than implementing the search in Python. Due to the very small input sizes, with at most 80 jewels and 80 stones, it doesn't really matter whether the search stops at the first jewel or goes through all the jewels.
Since the search takes about the same time in the best and worst cases, what makes the difference to the overall run-time is how often the counter is updated. In the best case (all stones are the first jewel) the counter is always incremented, whereas in the worst case (no stone is a jewel) the counter is never incremented. Hence, the worst case is faster than the best case.
The real issue is that I'm not generating worst cases. I'm not constructing inputs that make Algorithm 2 do the most work. A worst case should make the linear search go through all the jewels and increment the counter for each one. The worst case is actually when all stones are the last jewel.
I should go back, modify the worst_case function so that stones = chr(31 + j) * s, and run again the previous cell. Instead, I will run count_in_string on larger inputs. That will avoid the search taking about the same time whether a stone is the first jewel or not a jewel. This time I also ask for a graphical output.
time_cases(count_in_string, cases, start=1000, double=4, chart=True)\ntime_cases(count_in_string, cases, start=1000, double=4, chart=True)
Run-times for count_in_string\n\nInput size best_case normal_case worst_case \n 1000 14.6 34.7 35.4 \u00b5s\n 2000 30.3 107.4 116.4 \u00b5s\n 4000 61.4 332.3 386.1 \u00b5s\n 8000 123.6 1112.0 1359.6 \u00b5s\n 16000 248.5 3979.9 5061.5 \u00b5s
The best-case run-times double as the input size doubles, confirming the linear complexity. The worst-case run-times about quadruple as the input size doubles, confirming the quadratic complexity.
In\u00a0[14]: Copied!algorithms = [count_in_string, count_in_set, count_in_bag]\ntime_functions(algorithms, normal_case, 1000, 4, chart=True)\nalgorithms = [count_in_string, count_in_set, count_in_bag] time_functions(algorithms, normal_case, 1000, 4, chart=True)
Inputs generated by normal_case\n\nInput size count_in_string count_in_set count_in_bag \n 1000 36.6 36.6 67.6 \u00b5s\n 2000 111.4 89.2 147.5 \u00b5s\n 4000 339.8 189.6 309.0 \u00b5s\n 8000 1124.1 411.1 633.5 \u00b5s\n 16000 4014.9 851.0 1297.3 \u00b5s
As expected, using a set or bag pays off as the input size increases: as there are more jewels and stones, the linear search takes longer, but looking up a stone in a set of jewels or a jewel in a bag of stones takes constant time. However, for small inputs, a linear search is fast and hence the extra time to create the additional data structure doesn't pay off.
Using a set of jewels is about twice as fast as using a bag of stones, maybe because set is built-in and implemented in C, a very fast language, whereas Counter is part of the standard library implemented in Python, which is much slower. This example shows that algorithms with the same complexity can perform differently in practice, because the complexity tells us how the run-times grow, but not how fast or slow they are.
Michel Wermelinger, 23 January 2024, last updated 13 March 2024
"},{"location":"essays/example-jewels/#1-tests","title":"1 Tests\u00b6","text":"Before thinking of any solution, I write down some tests. Each test is two input strings and the expected integer output. I need to think of edge cases: inputs that are extreme values or that lead to extreme outputs.
For this problem, one edge case is that none of the stones is a jewel, which can happen in several ways: there are no stones; there are no jewels; there are stones and jewels but no character in stones occurs in jewels. Note that the problem statement doesn't prevent the strings to be empty, so we must assume they may be.
Another edge case is that all stones are jewels, which again can happen in several ways: the two input strings are the same; all stones are the same jewel; each stone is a jewel but not all jewels are among the stones.
Besides the edge cases I must also consider normal cases, where the stones include jewels and non-jewels and where the stones don't appear in the same order as the jewels.
I write the tests succinctly as a table, with one row per test, and one column with a string describing the test, one column per input, and a final column with the expected output. Later, I will use a function from algoesup to run all the tests and report those where the actual outputs differ from the expected ones.
Next I think of possible algorithms and their complexity, to decide which ones are worth implementing.
"},{"location":"essays/example-jewels/#21-without-additional-data","title":"2.1 Without additional data\u00b6","text":"I first attempt to solve the problem directly on the input strings. One approach that comes to mind is to count how often each jewel occurs among the stones.
Algorithm 1: Set a counter to zero. For each jewel, iterate over the stones. If a stone is the same as the current jewel, increment the counter. After going through all jewels, return the counter.
If j is the number of jewels and s the number of stones, then this algorithm always has complexity j \u00d7 \u0398(s) = \u0398(j \u00d7 s) because it does at most two constant-time operations, checking equality and incrementing the counter, for each jewel and stone.
The first approach searches each jewel among the stones. The symmetric approach is to search each stone among the jewels:
Algorithm 2: Set a counter to zero. For each stone, do a linear search for it among the jewels. If it is found, increment the counter. After going through all stones, return the counter.
In the best case, each stone is the first jewel, and the search takes constant time. The best-case complexity is s \u00d7 \u0398(1) = \u0398(s). In the worst case, the search goes through all the jewels, because the stone isn't a jewel or is the last jewel. The worst-case complexity is s \u00d7 \u0398(j) = \u0398(s \u00d7 j).
"},{"location":"essays/example-jewels/#22-with-additional-data","title":"2.2 With additional data\u00b6","text":"My next attempts consider pre-processing the inputs to make the searches faster.
Algorithm 1 goes through the stones j times, each time counting how often a jewel occurs. It's more efficient to go through the stones only once, counting how often each stone occurs, and then add the counts of those that are jewels. We need to know the frequency of each stone and the natural data type for that is the bag (or multiset).
Algorithm 3: Put all stones in a bag. Initialise a counter to zero. For each jewel, add to the counter the frequency of that jewel in the bag. Return the value of the counter.
If the bag type is implemented efficiently, both adding an item and obtaining its frequency take constant time. The complexity of Algorithm 3 is thus s \u00d7 \u0398(1) + j \u00d7 \u0398(1) = \u0398(s + j).
Algorithm 2 checks if each stone is a jewel. Is there an abstract data type (ADT) that provides such an operation? Yes, the set ADT allows checking if an item is a member of a set, which leads to...
Algorithm 4: Put all jewels in a set. Initialise a counter to zero. For each stone, if it is a member of the set, increment the counter. Return the value of the counter.
If the set ADT is implemented efficiently, both adding an item and checking membership take constant time. The complexity of Algorithm 4 is thus j \u00d7 \u0398(1) + s \u00d7 \u0398(1) = \u0398(j + s).
"},{"location":"essays/example-jewels/#23-with-sorting","title":"2.3 With sorting\u00b6","text":"The order of jewels and stones in the input strings doesn't affect the output (the number of stones that are jewels). I can thus sort the jewels, the stones, or both, to use logarithmic binary search instead of linear search.
However, sorting takes linear time in the best case and log-linear or quadratic time in the worst case. I already have algorithms that are linear in the total size of the input, so sorting wouldn't be more efficient. I therefore do not further pursue this approach.
"},{"location":"essays/example-jewels/#24-summary","title":"2.4 Summary\u00b6","text":"Algorithms 1 and 2 don't use additional memory, but have complexity \u0398(j \u00d7 s), while Algorithms 3 and 4 have better complexity \u0398(j + s), but have the run-time and memory overhead of an additional data structure. In practice, Algorithms 3 and 4 might be slower than Algorithms 1 and 2, so it's best to implement all of them.
However, Algorithm 1 always takes \u0398(j \u00d7 s) whereas Algorithm 2 only does so in the worst case. I therefore won't implement Algorithm 1.
Algorithm 3 creates a set with j jewels, whereas Algorithm 4 creates a bag with s stones. Typically, we expect inputs to have more stones than jewels (j < s), so Algorithm 3 is likely to be faster. Nevertheless, I'll implement Algorithm 4 too, for comparison.
"},{"location":"essays/example-jewels/#3-code","title":"3 Code\u00b6","text":"The next function implements Algorithm 2, using Python's in operator to do the linear search.
Finally, I will measure the run-times of the above functions with the algoesup library. The library expects us to define functions that construct inputs for a given total size.
This problem has two inputs, so I must decide how to divide the total size among both strings. I'll divide it equally: s = j. (For odd n, s = j + 1.) In that way, the expected run-times will be linear or quadratic in s: \u0398(s + j) = \u0398(2s) = \u0398(s) or \u0398(s \u00d7 j) = \u0398(s\u00b2). This makes it easy to check them empirically.
I write a function to generate a best-case input: each stone is the first jewel. To generate the input strings, I use Python's built-in chr function to obtain a character, given its Unicode number. The first 31 characters are mostly unprintable control characters, so I start at code 32 (space character).
Algorithms 3 and 4 always have the same complexity, but not so for Algorithm 2. I can measure its run-times on best, typical and worst cases, using the library's time_cases. I start with an input size of 10 and double it four times to 20, 40, 80 and 160.
The library provides time_functions to measure the run-times of up to 6 functions on the same inputs. I run the three implemented algorithms on typical inputs, with the same sizes as before.
This essay explored a simple problem: how many of the characters in a string occur in another string? There are at least 7 algorithms: 2 don't require any additional data structure, 2 use a set or a bag to achieve constant-time searches, and 3 other sort one or both inputs. Three of the first four algorithms were implemented in Python and their run-times measured. Using a set is the best option: the complexity is the lowest possible (linear in the total size of the inputs), and the run-times are better than using a bag.
"},{"location":"essays/example-two-sum-2/","title":"Two Sum (two solutions)","text":"This simple algorithmic essay aims to solve the classic Two Sum problem from LeetCode.
Readers should have an intermediate understanding of Python to understand this essay.
In\u00a0[1]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff In\u00a0[2]: Copied!
from algoesup import test, time_functions\nfrom algoesup import test, time_functions In\u00a0[3]: Copied!
%load_ext algoesup.magics\n%ruff on\n%allowed on\n%load_ext algoesup.magics %ruff on %allowed on
ruff was activated\nallowed was activated\nIn\u00a0[4]: Copied!
two_sum_tests = [\n # [\"description\", nums, target, expected_output],\n [\"minimum size for nums\", [1, 2], 3, (0, 1)],\n [\"non-adjacent indices\", [1, 4, 9, 7], 8, (0, 3)],\n [\"first two elements\", [5, 7, 1, 2, 8], 12, (0, 1)],\n [\"last two elements\", [1, 3, 5, 7, 8], 15, (3, 4)],\n [\"repeated elements\", [6, 2, 3, 2], 4, (1, 3)],\n [\"max and min range\", [-109, 109, 0], 0, (0, 1)],\n [\"lowest target value\", [-50, 1, -59], -109, (0, 2)],\n [\"highest target value\", [50, 1, 59], 109, (0, 2)],\n]\ntwo_sum_tests = [ # [\"description\", nums, target, expected_output], [\"minimum size for nums\", [1, 2], 3, (0, 1)], [\"non-adjacent indices\", [1, 4, 9, 7], 8, (0, 3)], [\"first two elements\", [5, 7, 1, 2, 8], 12, (0, 1)], [\"last two elements\", [1, 3, 5, 7, 8], 15, (3, 4)], [\"repeated elements\", [6, 2, 3, 2], 4, (1, 3)], [\"max and min range\", [-109, 109, 0], 0, (0, 1)], [\"lowest target value\", [-50, 1, -59], -109, (0, 2)], [\"highest target value\", [50, 1, 59], 109, (0, 2)], ] In\u00a0[5]: Copied!
def two_sum_bf(nums, target):\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\"\"\"\n for index_1 in range(len(nums)):\n for index_2 in range(len(nums)):\n if index_1 != index_2 and nums[index_1] + nums[index_2] == target:\n return index_1, index_2\n\ntest(two_sum_bf, two_sum_tests)\ndef two_sum_bf(nums, target): \"\"\"Given a list of integers return the indices of the pair that sums to target.\"\"\" for index_1 in range(len(nums)): for index_2 in range(len(nums)): if index_1 != index_2 and nums[index_1] + nums[index_2] == target: return index_1, index_2 test(two_sum_bf, two_sum_tests)
Testing two_sum_bf...\nTests finished: 8 passed, 0 failed.\n
Next up is the Mapping algorithm implemented using Python's dict.
def two_sum_map(nums, target):\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\"\"\"\n differences = {}\n for index in range(len(nums)):\n difference = target - nums[index]\n if nums[index] in differences:\n return differences[nums[index]], index\n differences[difference] = index\n\ntest(two_sum_map, two_sum_tests)\n def two_sum_map(nums, target): \"\"\"Given a list of integers return the indices of the pair that sums to target.\"\"\" differences = {} for index in range(len(nums)): difference = target - nums[index] if nums[index] in differences: return differences[nums[index]], index differences[difference] = index test(two_sum_map, two_sum_tests) Testing two_sum_map...\nTests finished: 8 passed, 0 failed.\nIn\u00a0[7]: Copied!
def worst(size):\n \"\"\"Given a size, generate a worst-case problem instance for two sum.\"\"\"\n nums = [0] * (size - 2) + [1, 1]\n target = 2\n return (nums, target)\ndef worst(size): \"\"\"Given a size, generate a worst-case problem instance for two sum.\"\"\" nums = [0] * (size - 2) + [1, 1] target = 2 return (nums, target) In\u00a0[8]: Copied!
solutions = [two_sum_bf, two_sum_map]\ntime_functions(solutions, worst, start=100, double=4, chart=True)\nsolutions = [two_sum_bf, two_sum_map] time_functions(solutions, worst, start=100, double=4, chart=True)
Inputs generated by worst\n\nInput size two_sum_bf two_sum_map \n 100 454.4 5.7 \u00b5s\n 200 1906.9 11.1 \u00b5s\n 400 7516.0 22.5 \u00b5s\n 800 30797.2 45.9 \u00b5s\n 1600 125003.9 93.3 \u00b5s
The numbers printed before the chart represent the run-times of our solutions in microseconds (\u00b5s) for increasing input sizes.
On the chart, the data points for two_sum_bf almost instantly eclipse that of two_sum_map. It looks as if the run-times for two_sum_map are not growing at all, but we know by looking at numbers above that this is not the case.
Let us see if we can modify the inputs of time_functions for a better visual representation.
solutions = [two_sum_bf, two_sum_map]\ntime_functions(solutions, worst, start=1, double=4, text=False, chart=True)\nsolutions = [two_sum_bf, two_sum_map] time_functions(solutions, worst, start=1, double=4, text=False, chart=True)
We changed the initial input size to 1, and the trend of the run-times is a little clearer now. The Brute force algorithm's run-time's still accelerate off into the stratosphere, but we can see the separation and trend of the Mapping algorithm a little better.
"},{"location":"essays/example-two-sum-2/#two-sum-two-solutions","title":"Two Sum (two solutions)\u00b6","text":"Michael Snowden, 24 January 2024, last updated 16 March 2024
"},{"location":"essays/example-two-sum-2/#1-problem","title":"1 Problem\u00b6","text":"Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.
nums[i] $\\leq 109$target $\\leq 109$With our problem defined, the next step is to think of ways to solve it. This section presents two approaches to solving Two Sum: brute force, and mapping.
"},{"location":"essays/example-two-sum-2/#21-brute-force","title":"2.1 Brute force\u00b6","text":"Generally speaking, a brute force algorithm tries all possibilities, and selects a correct one. For this problem, the possibilities are all sums that can be obtained by pairing each number in nums with every other number, and the correct pair is selected when the sum matches target.
Brute force algorithm: An outer loop iterates through each number in nums, then for each number, an inner loop iterates nums again. For each pair of numbers, if their indices are different and their sum matches target, return their indices.
In the Brute force algorithm, we checked each pair of numbers in nums to see if the resulting sum was equal to target. Since we are already checking every number in the list, why not store some piece information from each number that will help us find our matching pair?
For every number in nums, we can map the difference between it and the target (target - number) to its corresponding index using a hashtable. This allows us to check the hashtable for matching numbers much faster.
Mapping algorithm: For each number in nums, if it's in the hashmap, return its index and the index mapped to it. Otherwise, calculate the difference (target - number) and map it to the corresponding index of number.
In this section we will implement and test the algorithms.
"},{"location":"essays/example-two-sum-2/#31-testing","title":"3.1 Testing\u00b6","text":"We start off by writing some tests.
To test the above solutions, we need to consider edge cases and other important functional tests. We should include tests for the minimum input size, and any extremes values that can be present. When integers are part of the input, and there are no restrictions, negative numbers and zero should be added to the tests.
"},{"location":"essays/example-two-sum-2/#32-implementations","title":"3.2 Implementations\u00b6","text":"The next cell implements the Brute force algorithm using nested for loops
In this section we measure the run-times of our solutions under certain conditions and discuss the results.
"},{"location":"essays/example-two-sum-2/#41-generating-inputs","title":"4.1 Generating inputs\u00b6","text":"Since time_functions from the algoesup library requires code to generate inputs, we shall write that first.
It is often useful to measure the run-times of a solution when it is doing the most work; this is called the worst-case. We want to generate inputs that will take our solution the most time to complete, and this happens when the two numbers that sum to target are the last two.
We now compare worst-case runtimes for both solutions. The input has an initial size of 100, and is doubled 4 times; the run times are measured for the initial size, then each time it is doubled.
"},{"location":"essays/example-two-sum-2/#5-conclusion","title":"5 Conclusion\u00b6","text":"We started this essay with the definition of the Two Sum problem. Next, we outlined two algorithms: brute force, and mapping . After that, we implemented and tested our solutions using Python, and in the penultimate section we used empirical testing and discussed the results. Now we must decide which of our algorithms is best.
The Brute force algorithm is not very efficient when it comes to run-times. When the size of the input increases the run-times increase by a large amount. The one redeeming aspect of this algorithm is the efficient memory usage which is achieved by not using any additional data structures like dictionaries.
In contrast, the Mapping algorithm is reasonably efficient in terms of run times, but this is achieved by using extra memory in the form of the dictionary. In the final analysis, the slow run-times of the brute force algorithm cannot be ignored. The small trade of memory for faster run-times is worth it in this instance. We therefore conclude the mapping algorithm is best.
"},{"location":"essays/example-two-sum-3/","title":"Two sum (three solutions)","text":"In this extended algorithmic essay we aim to solve the classic Two Sum problem from LeetCode. We are going to explore, analyse, and compare a selection of approaches with the end goal of finding a clear and efficient solution.
We assume the reader has an intermediate understanding of Python, including aspects like importing modules, using loops, and applying conditionals. Furthermore, Big-Oh notation is used to analyse the complexity of our solutions and we refer to terms such as binary search and brute force.
In\u00a0[1]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff pytype\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff pytype In\u00a0[2]: Copied!
from algoesup import test, time_functions, time_cases\nfrom algoesup import test, time_functions, time_cases In\u00a0[3]: Copied!
%load_ext algoesup.magics\n%ruff on\n%allowed on\n%load_ext algoesup.magics %ruff on %allowed on
ruff was activated\nallowed was activated\nIn\u00a0[4]: Copied!
two_sum_tests = [\n # [\"description\", nums, target, expected_output]\n [\"minimum size for nums\", [1, 2], 3, (0, 1)],\n [\"non-adjacent indices\", [1, 4, 9, 7], 8, (0, 3)],\n [\"first two elements\", [5, 7, 1, 2, 8], 12, (0, 1)],\n [\"last two elements\", [1, 3, 5, 7, 8], 15, (3, 4)],\n [\"repeated elements\", [6, 2, 3, 2], 4, (1, 3)],\n [\"max and min range\", [-109, 109, 0], 0, (0, 1)],\n [\"lowest target value\", [-50, 1, -59], -109, (0, 2)],\n [\"highest target value\", [50, 1, 59], 109, (0, 2)],\n]\ntwo_sum_tests = [ # [\"description\", nums, target, expected_output] [\"minimum size for nums\", [1, 2], 3, (0, 1)], [\"non-adjacent indices\", [1, 4, 9, 7], 8, (0, 3)], [\"first two elements\", [5, 7, 1, 2, 8], 12, (0, 1)], [\"last two elements\", [1, 3, 5, 7, 8], 15, (3, 4)], [\"repeated elements\", [6, 2, 3, 2], 4, (1, 3)], [\"max and min range\", [-109, 109, 0], 0, (0, 1)], [\"lowest target value\", [-50, 1, -59], -109, (0, 2)], [\"highest target value\", [50, 1, 59], 109, (0, 2)], ] In\u00a0[5]: Copied!
def two_sum_bf(nums: list, target: int) -> tuple[int, int]:\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\n\n Preconditions:\n len(nums) >= 2\n -109 <= nums[i] <= 109\n -109 <= target <= 109\n Exactly one pair a and b in nums has a + b = target\n \"\"\"\n for index_1 in range(len(nums)):\n for index_2 in range(len(nums)):\n if index_1 != index_2 and nums[index_1] + nums[index_2] == target:\n return index_1, index_2\n\ntest(two_sum_bf, two_sum_tests)\ndef two_sum_bf(nums: list, target: int) -> tuple[int, int]: \"\"\"Given a list of integers return the indices of the pair that sums to target. Preconditions: len(nums) >= 2 -109 <= nums[i] <= 109 -109 <= target <= 109 Exactly one pair a and b in nums has a + b = target \"\"\" for index_1 in range(len(nums)): for index_2 in range(len(nums)): if index_1 != index_2 and nums[index_1] + nums[index_2] == target: return index_1, index_2 test(two_sum_bf, two_sum_tests)
Testing two_sum_bf...\nTests finished: 8 passed, 0 failed.\n
Next up is the approach that uses sorting.
In\u00a0[6]: Copied!def two_sum_sort(nums: list, target: int) -> tuple[int, int]:\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\n\n Preconditions:\n len(nums) >= 2\n -109 <= nums[i] <= 109\n -109 <= target <= 109\n Exactly one pair a and b in nums has a + b = target\n \"\"\"\n pairs = []\n for index in range(len(nums)):\n pairs.append((nums[index], index))\n pairs.sort()\n start = 0\n end = len(nums) - 1\n while start < end:\n current_sum = pairs[start][0] + pairs[end][0]\n if current_sum == target:\n # return the indices in ascending order for reliable testing\n lower_index = min(pairs[start][1], pairs[end][1])\n upper_index = max(pairs[start][1], pairs[end][1])\n indices = (lower_index, upper_index)\n return indices\n if current_sum < target:\n start = start + 1\n else:\n end = end - 1\n\ntest(two_sum_sort, two_sum_tests)\ndef two_sum_sort(nums: list, target: int) -> tuple[int, int]: \"\"\"Given a list of integers return the indices of the pair that sums to target. Preconditions: len(nums) >= 2 -109 <= nums[i] <= 109 -109 <= target <= 109 Exactly one pair a and b in nums has a + b = target \"\"\" pairs = [] for index in range(len(nums)): pairs.append((nums[index], index)) pairs.sort() start = 0 end = len(nums) - 1 while start < end: current_sum = pairs[start][0] + pairs[end][0] if current_sum == target: # return the indices in ascending order for reliable testing lower_index = min(pairs[start][1], pairs[end][1]) upper_index = max(pairs[start][1], pairs[end][1]) indices = (lower_index, upper_index) return indices if current_sum < target: start = start + 1 else: end = end - 1 test(two_sum_sort, two_sum_tests)
Testing two_sum_sort...\nTests finished: 8 passed, 0 failed.\n
Finally, the mapping algorithm is implemented using Python's dict.
def two_sum_map(nums: list, target: int) -> tuple[int, int]:\n \"\"\"Given a list of integers return the indices of the pair that sums to target.\n\n Preconditions:\n len(nums) >= 2\n -109 <= nums[i] <= 109\n -109 <= target <= 109\n Exactly one pair a and b in nums has a + b = target\n \"\"\"\n differences: dict[int, int] = {} # allowed\n for index in range(len(nums)):\n difference = target - nums[index]\n if nums[index] in differences:\n return differences[nums[index]], index\n differences[difference] = index\n\ntest(two_sum_map, two_sum_tests)\n def two_sum_map(nums: list, target: int) -> tuple[int, int]: \"\"\"Given a list of integers return the indices of the pair that sums to target. Preconditions: len(nums) >= 2 -109 <= nums[i] <= 109 -109 <= target <= 109 Exactly one pair a and b in nums has a + b = target \"\"\" differences: dict[int, int] = {} # allowed for index in range(len(nums)): difference = target - nums[index] if nums[index] in differences: return differences[nums[index]], index differences[difference] = index test(two_sum_map, two_sum_tests) Testing two_sum_map...\nTests finished: 8 passed, 0 failed.\n
The brute force algorithm comes out on top in terms of simplicity, it is just a case of checking every pair of numbers. The double pointer approach seems like the most convoluted with the mapping differences algorithm somewhere in the middle of the two.
In\u00a0[8]: Copied!def best(size: int) -> tuple[list[int], int]:\n \"\"\"Given a size, generate a best case instance for Two Sum.\n\n Preconditions: size >= 2\n \"\"\"\n nums = [1, 1] + [0] * (size - 2)\n target = 2\n return (nums, target)\n\ndef normal(size: int) -> tuple[list[int], int]:\n \"\"\"Given a size, generate a normal case instance for Two Sum.\n\n Preconditions: size >= 2\n \"\"\"\n nums = [0] * size\n nums[size // 2 - 1:size // 2 + 1] = [1, 1]\n target = 2\n return (nums, target)\n\ndef worst(size: int) -> tuple[list[int], int]:\n \"\"\"Given a size, generate a worst case instance for Two Sum.\n\n Preconditions: size >= 2\n \"\"\"\n nums = [0] * (size - 2) + [1, 1]\n target = 2\n return (nums, target)\ndef best(size: int) -> tuple[list[int], int]: \"\"\"Given a size, generate a best case instance for Two Sum. Preconditions: size >= 2 \"\"\" nums = [1, 1] + [0] * (size - 2) target = 2 return (nums, target) def normal(size: int) -> tuple[list[int], int]: \"\"\"Given a size, generate a normal case instance for Two Sum. Preconditions: size >= 2 \"\"\" nums = [0] * size nums[size // 2 - 1:size // 2 + 1] = [1, 1] target = 2 return (nums, target) def worst(size: int) -> tuple[list[int], int]: \"\"\"Given a size, generate a worst case instance for Two Sum. Preconditions: size >= 2 \"\"\" nums = [0] * (size - 2) + [1, 1] target = 2 return (nums, target)
First let us see the run-times of two_sum_bf for best, normal and worst-case instances. Note the input size starts at 100 and is doubled 4 times reaching 1600 for the last data point.
input_generators = [worst, normal, best]\ntime_cases(two_sum_bf, input_generators, start=100, double=4, chart=True)\ninput_generators = [worst, normal, best] time_cases(two_sum_bf, input_generators, start=100, double=4, chart=True)
Run-times for two_sum_bf\n\nInput size worst normal best \n 100 454.6 228.8 0.3 \u00b5s\n 200 1817.9 1046.2 0.3 \u00b5s\n 400 7488.9 3722.6 0.3 \u00b5s\n 800 30940.9 15670.3 0.3 \u00b5s\n 1600 124206.2 62150.1 0.3 \u00b5s
We can see from the chart and run-times above, that our analysis of quadratic time complexity for the worst-case seems to line up with the data. As we double the input size, the run-times quadruple. For the best case, the run-times generally stay the same for increasing inputs suggesting constant time complexity. The normal case is somewhere in the middle of the two.
Now let us do the same for two_sum_map.
input_generators = [worst, normal, best]\ntime_cases(two_sum_map, input_generators, start=100, double=4, chart=True)\ninput_generators = [worst, normal, best] time_cases(two_sum_map, input_generators, start=100, double=4, chart=True)
Run-times for two_sum_map\n\nInput size worst normal best \n 100 5.7 3.0 0.3 \u00b5s\n 200 11.2 5.7 0.3 \u00b5s\n 400 22.7 11.2 0.3 \u00b5s\n 800 46.3 22.7 0.3 \u00b5s\n 1600 93.5 46.4 0.3 \u00b5s
The first thing to note is the dramatic reduction in size of the run-times. The scales on the y-axis differ by orders of magnitude. Also, the plot for our worst-case on this chart has a much straighter line with run-times doubling in proportion with input size. This aligns with our prediction of linear time complexity.
In\u00a0[11]: Copied!solutions = [two_sum_bf, two_sum_sort, two_sum_map]\ntime_functions(solutions, worst, start=100, double=4, chart=True)\nsolutions = [two_sum_bf, two_sum_sort, two_sum_map] time_functions(solutions, worst, start=100, double=4, chart=True)
Inputs generated by worst\n\nInput size two_sum_bf two_sum_sort two_sum_map \n 100 455.2 14.5 5.7 \u00b5s\n 200 1816.7 28.4 11.1 \u00b5s\n 400 7499.5 57.4 22.7 \u00b5s\n 800 30764.1 116.3 46.3 \u00b5s\n 1600 124771.8 236.4 93.6 \u00b5s
The run-times for two_sum_bf almost instantly eclipse that of two_sum_sort and two_sum_map.On the chart it looks as if the run-times for two_sum_sort and two_sum_map are not growing at all, but we know by looking at the run-times above that this is not the case. Let us see if we can adjust the inputs of time_functions so the growth rates of the fastest two functions have a better visual representation in the chart.
solutions = [two_sum_bf, two_sum_sort, two_sum_map]\ntime_functions(solutions, worst, start=1, double=4, text=False, chart=True)\nsolutions = [two_sum_bf, two_sum_sort, two_sum_map] time_functions(solutions, worst, start=1, double=4, text=False, chart=True)
The point at which the growth rates start to diverge is much clearer now. The brute force approach's run-times still accelerate off into the stratosphere, but we can see the separation and trend of the sorting and mapping algorithms.
"},{"location":"essays/example-two-sum-3/#two-sum-three-solutions","title":"Two sum (three solutions)\u00b6","text":"Michael Snowden, 25 January 2024, last updated 16 March 2024
"},{"location":"essays/example-two-sum-3/#1-problem","title":"1 Problem\u00b6","text":"To effectively solve Two Sum, it is crucial we thoroughly understand the problem. We need to identify the inputs, outputs and the relationship between them.
Leetcode provides the following problem description.
\"Given an array of integers nums and an integer target, return indices of the two numbers such that they add up to target.\"
nums[i] $\\leq 109$target $\\leq 109$We can extract some important information from their description, namely the pre- and post-conditions.
Preconditions:
nums[i] $\\leq 109$target $\\leq 109$a and b in nums has a + b = targetPostconditions:
Let indices be the output, then:
len(indices) = 2;nums[indices[0]] + nums[indices[1]] = targetThe preconditions must be satisfied for our algorithms to be defined, and the postconditions must be satisfied for our algorithms to be correct.
"},{"location":"essays/example-two-sum-3/#2-algorithms","title":"2 Algorithms\u00b6","text":"With our problem defined, the next step is to think of ways to solve it. This section presents three distinct approaches to solving Two sum: brute force, sorting and mapping.
"},{"location":"essays/example-two-sum-3/#21-brute-force","title":"2.1 Brute force\u00b6","text":"Generally speaking, a brute force algorithm tries all possibilities, and selects a correct one. For this problem, the possibilities are all sums that can be obtained by pairing each number in nums with every other number, and the correct pair is identified if the sum matches target. We are checking all possible sums, so we are sure to find our indices if they exist. Looking back at the preconditions, we can see that each problem instance must have exactly one pair that sums to target. Hence this approach is guaranteed to find a solution, as long as our preconditions are met.
Getting any working solution regardless of efficiency can be an important first step. Sometimes we need to solve a problem quickly, and more importantly it gets us thinking through it, which can often lead to additional solutions.
Brute force algorithm: An outer loop iterates through each number in nums, then for each number, an inner loop iterates nums again. For each pair of numbers, if their indices are different and their sum matches target, return their indices.
1. for each index_1 from 0 to len(nums)-1:\n 1. for each index_2 from 0 to len(nums)-1:\n 1. if index_1 != index_2 and nums[index_1] + nums[index_2] == target:\n 1. let indices be (index_1, index_2)\n 2. stop\n
Let n = len(nums), then this algorithm has two nested for loops that do n iterations each. The operations performed within the inner loop are constant time, meaning this solution will do at most n $\\times$ n $\\times$ O(1) steps. Thus, the worst-case time complexity is O(n $^2$). In the best-case, the first and second numbers in nums sum to target. No matter the size of nums, the run-times would not increase. Therefore, the best-case time complexity would be O(1).
For many computational problems a good question to ask is: will sorting the inputs simplify the problem and lead to a more efficient solution? In this case, the answer is yes, we can exploit the properties of a sorted input in a similar way to binary search. Rather than focusing on the middle of the sequence and reducing the search space by half, we keep track of the two ends with position variables and have reduce the search space by one each time. This kind of approach is commonly referred to as a \"double pointer algorithm\" named after the two position variables.
Before we move on to a formal description of the algorithm, we need to consider a crucial aspect of the Two Sum problem: it requires indices to be returned. This has implications for our solution: direct sorting of nums is not possible because the original index positions would be altered. Thus, any additional data structures we use must keep track of the corresponding indices from elements of nums. Keeping this in mind, here is the description of our algorithm.
With sorting algorithm: Create a pair (number, index) for each number in nums. Add each pair to a list pairs, then sort the list into ascending order based on the numbers. Initialise two variables start and end to be 0 and len(nums) - 1 respectively. While start $\\neq$ end sum the numbers in pairs corresponding to the indices start and end. If the sum is less than target, move start to the right by incrementing its value by one. If the sum is greater than target, move end to the left by decrementing its value by one. If the sum matches target then return the indices of both numbers.
The logic of this strategy is as follows. The sum of the numbers at positions start and end in our pairs list will have one of the following three cases: the sum can be equal to, greater than or less than target. If the sum is equal to target, then we have found our solution and can return the indices. If the sum is less than target, we need to increase the value of our sum; the only way to do this is by moving start to the right. Remember we have sorted the list, so all values to the right are greater. If our sum is greater than target we need to decrease the value of our sum, and the only way to do that by moving end to the left.
1. let pairs be an empty list\n2. for each index from 0 to len(nums):\n 1. let `pair be (nums[index], index)\n 2. append pair to `pairs`\n3. let pairs be sorted by value at first index\n4. let start = 0\n5. let end = len(nums) -1\n6. while start != end:\n 1. pair_sum = pairs[start][0] + pairs[end][0]\n 2. if pairs_sum = target:\n 1. let indices be (pairs[start][1], pairs[end][1])\n 2. stop\n 3. otherwise if pairs_sum > target:\n 1. let end = end - 1\n 4. otherwise:\n 1. let start = start + 1\n
The important parts of this algorithm with respect analysing time complexity are: the for loop at step number two, the sorting operation at step number three and the while loop at step number six.
Let n = len(nums), then the for loop always does n iterations, and we will assume the sorting operation has worst-case complexity of O(n log(n)) and best-case of O(n), that just leaves the while loop. The while loop will do at most n iterations in a scenario where one of the variables start or end stays in place and the other is incremented until they are next to each other.
It is clear now that the sorting operation will dominate this approach when it comes to time complexity. Therefore, this algorithm has an overall worst-case time complexity of O(n log(n)) and a best-case of O(n).
"},{"location":"essays/example-two-sum-3/#23-mapping","title":"2.3 Mapping\u00b6","text":"In the previous algorithm we paired each number in nums with its index out of necessity. We wanted to sort nums without loosing the original paring of number to index. This action of pairing numbers to indices is a useful idea; what if instead of pairing a number directly to its index, we paired the difference between our number and the target (i.e. target - number) to its index? If we did that, then finding our pair would be a case of checking if current number is in the pairs list.
This is a good start, but we still have a problem, the lookup operation takes linear time for a list. We need an alternative data structure, one with much efficient lookup times. If fast lookup times are required, then we should always consider a hashtable. This data structure is known informally by many different names such as dictionary, hashmap, map and associative array. A key property of this data structure is the lookup operation has constant time complexity in the average case.
For every number in nums, we can map the difference between it and the target (target - number) to its corresponding index using a hashtable. This allows us to check the hashmap for matching numbers in constant time.
Mapping algorithm: For each number in nums, if its in the hashmap, return its index and the index mapped to it. Otherwise, calculate the difference (target - number) and map it to the corresponding index of number.
1. let differences be an empty dictionary\n2. for index from 0 to len(nums) - 1:\n 1. if nums[index] in differences:\n 1.let indices be (differences[nums[index]], index)\n 2. stop\n 2. otherwise:\n 1. let difference = target - nums[index]\n 2. let differences[difference] = index\n
Let n = len(nums), then this algorithm has a single loop that does n iterations. Because we are using a hashmap, all the operations performed in the loop are done in constant time. Thus, our mapping algorithm has O(n) time complexity in in the worst-case. Similar to the brute force approach, if the correctly summing numbers are in the first two positions of nums, then the run-times will be unaffected by increasing input sizes, giving a best-case complexity of O(1).
Many times a brute force approach is a good starting point; it is a simple strategy that is easy to implement. Moreover, this strategy is efficient in terms of its memory usage when compared to the other algorithms; it does not use additional data structures. However, this approach has an undesirable O(n $^2$) worst-case time complexity. Every time we double the input size, the run-times increase fourfold.
Our next approach used sorting to endow our list with properties useful for searching. This algorithm is perhaps the most convoluted and maybe harder to think through relative to the others. Furthermore, it requires additional memory compared to the brute force approach. The benefits of the strategy are the O(n log(n)) worst-case time complexity which improves considerably on the brute force algorithm.
The third solution made a single pass through nums and used a hashtable to map differences to indexes. While not as simple as the brute force algorithm, this approach is not hard to follow nor understand; everything is carried out in a single loop. On the other hand, this approach has the additional memory overhead of the hashtable itself, which needs to be taken into account. The main advantage with this approach is the O(n) time complexity for the worst-case, making it the most efficient when it comes to scaling run-times with input size.
When considering all three approaches, and taking into account aspects of efficiency as well as readability, the mapping algorithm seems to come out on top. It makes that that classic space-time trade off i.e sacrifices some memory efficiency for time efficiency, but the simplicity of the approach combined with the efficient time complexity makes it a worth while exchange.
"},{"location":"essays/example-two-sum-3/#3-code","title":"3 Code\u00b6","text":"In this section we will implement the algorithms. We shall do so using a basic subset of Python in the hope of making our code as language agnostic as possible.
Throughout this section we will make use of code quality tools such as linters and type checkers to help us meet the standards expected for clean readable and error free code.
"},{"location":"essays/example-two-sum-3/#31-preparation-and-imports","title":"3.1 Preparation and imports\u00b6","text":"The next two cells set up the automatic type checking linting and Construct checking for our code cells. We also import some of the functions we will use to test, time and generate instances for our solutions.
If one or more of the styling or type checking ideals are violated, the warnings will be printed alongside the corresponding line number underneath the offending cell.
"},{"location":"essays/example-two-sum-3/#32-testing","title":"3.2 Testing\u00b6","text":"Before We start implementing our algorithms, we write some tests. The test() function from the algoesup library is a simple way to test for correctness. It takes a function and a test table then reports any failed tests.
To test the algorithms, we need to consider edge cases and other important functional tests. Edge cases often occur at the extreme ends of the spectrum of allowed inputs or outputs, they should ideally test unexpected conditions that might reveal bugs in the code. For the Two Sum problem, we should test the minimum size for nums and also the extremes of the values that can be present. We should include negative numbers and zero in our tests because integers are present in the inputs.
The cell below contains our test table, note the descriptions of each case in the first column, and how the boundary cases, negative numbers and zero are all present in the table.
"},{"location":"essays/example-two-sum-3/#33-implementations","title":"3.3 Implementations\u00b6","text":"The next cell implements the brute force algorithm using nested for loops and a conditional to check for the correct pair. Note how this conditional looks similar to one of the postconditions; this is a good sign.
In this section we will measure the run-times of our solutions under various conditions to see if our analysis matches the results.
"},{"location":"essays/example-two-sum-3/#41-generating-inputs","title":"4.1 generating inputs\u00b6","text":"time_functions and time_cases from the algoesup library require a function that generates problem instances of a given size. We want to be able to generate instances that correspond to best, normal and worst cases for the solutions were appropriate.
The best normal and worst case scenarios might not always be the same for each algorithm, for example, the best-case for two_sum_bf and two_sum_map would be when the first two numbers encountered sum to target but this is not the case for two_sum_sort where the best-case would be dependent on the sorting algorithm.
Since two_sum_bf and two_sum_map share the same best- and worst-case scenarios, we shall focus on those for our input generators. For the normal-case the matching numbers will be in the middle two positions of nums
Let us now compare the worst-case run-times for all three solutions side by side.
"},{"location":"essays/example-two-sum-3/#5-conclusion","title":"5 Conclusion\u00b6","text":"We started this essay by defining the problem. We came up with three algorithms that used different approaches: brute force, sorting and mapping, then analysed the time complexity of each one. Next, we implemented and tested our solutions using Python, and in the penultimate section used empirical testing to see if our analysis matched the results. Now we must decide which of our algorithms is best.
The brute force approach, unsurprisingly, is not very efficient when it comes to run-times. We suspected this would be the case, then the empirical testing confirmed it. Its only positive attributes were its simplicity and efficient memory usage.
We are now left with a choice between the sorting and mapping approaches and I think there is a clear winner between the two. The mapping approach is more efficient in its worst-case complexity with O(n) compared to O(n log(n)) of the sorting, and on the surface seems simpler and easier to implement. Moreover, the mapping approach has the potential to be more memory efficient. For example, the sorting approach always has an auxiliary data structure the same size as nums, whereas the size of the dictionary will grow dynamically, only becoming the same size as nums in the worst case. Therefore, we must conclude the mapping algorithm is best.
This algorithmic essay template is for students of data structures and algorithms (DSA) courses. Throughout the template, there are links to relevant sections of our Writing and Coding Guide. Replace any text in italics by yours and delete this paragraph.
The introduction explains what the essay is about, the problem you are solving, and what you assume the reader to know. See our guidance on choosing a problem, writing the text and structuring the essay. This template follows the first structure in the guide. You don't need to change the following code cells.
In\u00a0[\u00a0]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff pytype\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff pytype In\u00a0[\u00a0]: Copied!
from algoesup import test, time_cases, time_functions\nfrom algoesup import test, time_cases, time_functions
For information on what the following commands do, see our guide's sections on type checking and linting and remove this paragraph.
In\u00a0[\u00a0]: Copied!%load_ext algoesup.magics\n# check the code's style\n%ruff on\n# check the data types\n%pytype on\n# optional: flag the Python constructs not taught in M269, our DSA course\n%allowed on\n%load_ext algoesup.magics # check the code's style %ruff on # check the data types %pytype on # optional: flag the Python constructs not taught in M269, our DSA course %allowed on In\u00a0[\u00a0]: Copied!
tests = [\n # Each line is a list or tuple of the form:\n # (description, input1, input2, ..., expected_output),\n]\ntests = [ # Each line is a list or tuple of the form: # (description, input1, input2, ..., expected_output), ] In\u00a0[\u00a0]: Copied!
# Replace solution_one with a more descriptive name.\ndef solution_one():\n # Implement your solution here\n pass\n\ntest(solution_one, tests)\n# Replace solution_one with a more descriptive name. def solution_one(): # Implement your solution here pass test(solution_one, tests) In\u00a0[\u00a0]: Copied!
# Replace solution_two with a more descriptive name.\ndef solution_two():\n # Implement your solution here\n pass\n\ntest(solution_two, tests)\n# Replace solution_two with a more descriptive name. def solution_two(): # Implement your solution here pass test(solution_two, tests) In\u00a0[\u00a0]: Copied!
# Replace solution_n with a more descriptive name.\ndef solution_n():\n # Implement your solution here\n pass\n\ntest(solution_n, tests)\n# Replace solution_n with a more descriptive name. def solution_n(): # Implement your solution here pass test(solution_n, tests) In\u00a0[\u00a0]: Copied!
def best_case(size: int) -> tuple[...]:\n # Implement your best-case input generator here.\n pass\ndef best_case(size: int) -> tuple[...]: # Implement your best-case input generator here. pass In\u00a0[\u00a0]: Copied!
def worst_case(size: int) -> tuple[...]:\n # Implement your worst-case input generator here.\n pass\ndef worst_case(size: int) -> tuple[...]: # Implement your worst-case input generator here. pass In\u00a0[\u00a0]: Copied!
def normal_case(size: int) -> tuple[...]:\n # Implement your normal-case input generator here.\n pass\ndef normal_case(size: int) -> tuple[...]: # Implement your normal-case input generator here. pass In\u00a0[\u00a0]: Copied!
cases = [best_case, normal_case, worst_case]\n# Change solution_n to the name of your solution.\ntime_cases(solution_n, cases, start=10, double=4)\ncases = [best_case, normal_case, worst_case] # Change solution_n to the name of your solution. time_cases(solution_n, cases, start=10, double=4)
Analyse the results. See the interpreting run-times section of our guide.
In\u00a0[\u00a0]: Copied!# Change solution_one, solution_two, and solution_n to the names of your solutions.\nalgorithms = [solution_one, solution_two, solution_n]\n# Replace normal_case with best_case or worst_case, if you wish.\ntime_functions(algorithms, normal_case, 1000, 4, chart=True)\n# Change solution_one, solution_two, and solution_n to the names of your solutions. algorithms = [solution_one, solution_two, solution_n] # Replace normal_case with best_case or worst_case, if you wish. time_functions(algorithms, normal_case, 1000, 4, chart=True)
Analyse the results. See the interpreting run-times section of our guide.
"},{"location":"essays/template-data-structures/#your-essays-title","title":"Your essay's title\u00b6","text":"Your (and any co-author's) name, current date
"},{"location":"essays/template-data-structures/#1-tests","title":"1 Tests\u00b6","text":"This section describes and defines the tests you will use to check your solutions. See the testing section of our guide.
"},{"location":"essays/template-data-structures/#2-algorithms","title":"2 Algorithms\u00b6","text":"This section outlines some algorithms that solve the problem. See the algorithms section of our guide.
"},{"location":"essays/template-data-structures/#21-first-algorithm-name","title":"2.1 First algorithm name\u00b6","text":"Describe your first strategy or approach.
Algorithm 1: Briefly describe your first algorithm.
Analyse at least the worst-case time complexity of your first algorithm.
"},{"location":"essays/template-data-structures/#22-second-algorithm-name","title":"2.2 Second algorithm name\u00b6","text":"Describe your second strategy or approach.
Algorithm 2: Briefly describe your second algorithm.
Analyse at least the worst-case time complexity of your second algorithm.
"},{"location":"essays/template-data-structures/#2n-nth-algorithm-name","title":"2.n nth algorithm name\u00b6","text":"Describe your nth strategy or approach.
Algorithm n: Briefly describe your nth algorithm.
Analyse at least the worst-case time complexity of your nth algorithm.
"},{"location":"essays/template-data-structures/#2n1-summary","title":"2.n+1 Summary\u00b6","text":"This section compares the previously outlined algorithms to inform implementation decisions.
"},{"location":"essays/template-data-structures/#3-code","title":"3 Code\u00b6","text":"This section implements and tests only the most promising algorithms. See the code section of our guide.
"},{"location":"essays/template-data-structures/#4-performance","title":"4 Performance\u00b6","text":"This section measures and compares the run-times of your implementations, so that you can check them against your earlier complexity analysis.
"},{"location":"essays/template-data-structures/#41-generating-inputs","title":"4.1 Generating inputs\u00b6","text":"Briefly describe your strategy and reasoning for generating the inputs.
"},{"location":"essays/template-data-structures/#42-best-normal-and-worst-run-times","title":"4.2 Best, normal and worst run-times\u00b6","text":"State which solutions(s) will be timed with best-, normal- or worst-case inputs. See the comparing cases and charting run-times sections of our guide.
"},{"location":"essays/template-data-structures/#43-fastest-and-slowest-algorithm","title":"4.3 Fastest and slowest algorithm\u00b6","text":"Compare the run times of all your solutions for the same case. See the comparing functions and charting run-times sections of our guide.
"},{"location":"essays/template-data-structures/#5-concluding-remarks","title":"5 Concluding remarks\u00b6","text":"Summarise your findings and conclude which solution is best.
After completing a draft of your essay, do a final check and then see the feedback guide on how to ask for, give, and handle comments.
"},{"location":"essays/template-data-structures/#6-acknowledgements","title":"6 Acknowledgements\u00b6","text":"Credit those who helped you create the essay. See the crediting feedback section of our guide.
"},{"location":"essays/template-intro-programming/","title":"Your essay's title","text":"This algorithmic essay template is for students of introductory programming courses. Throughout the template, there are links to relevant sections of our Writing and Coding Guide. Replace any text in italics by yours and delete this paragraph.
The introduction explains what the essay is about, the problem you are solving, and what you assume the reader to know. See our guidance on choosing a problem, writing the text and structuring the essay. This template follows the second structure in the guide. You don't need to change the following code cells.
In\u00a0[\u00a0]: Copied!import os\n\nif 'COLAB_GPU' in os.environ: # if we are in Google Colab...\n !pip install algoesup --no-deps\n !pip install allowed ruff\nimport os if 'COLAB_GPU' in os.environ: # if we are in Google Colab... !pip install algoesup --no-deps !pip install allowed ruff In\u00a0[\u00a0]: Copied!
# import functions to test the code and to measure the execution time\nfrom algoesup import test, time_functions_int\n# import functions to test the code and to measure the execution time from algoesup import test, time_functions_int
For information on what the following commands do, see our guide's section on linting and remove this paragraph.
In\u00a0[\u00a0]: Copied!%load_ext algoesup.magics\n# check the code's style\n%ruff on\n# optional: flag the Python constructs not taught in TM112, our introductory course\n%allowed on --config tm112.json\n%load_ext algoesup.magics # check the code's style %ruff on # optional: flag the Python constructs not taught in TM112, our introductory course %allowed on --config tm112.json In\u00a0[\u00a0]: Copied!
tests = [\n # Each line is a list or tuple of the form:\n # (description, input1, input2, ..., expected_output),\n]\ntests = [ # Each line is a list or tuple of the form: # (description, input1, input2, ..., expected_output), ] In\u00a0[\u00a0]: Copied!
def solution_one():\n # Implement your solution here\n pass\n\ntest(solution_one, tests)\ndef solution_one(): # Implement your solution here pass test(solution_one, tests) In\u00a0[\u00a0]: Copied!
def solution_two():\n # Implement your solution here\n pass\n\ntest(solution_two, tests)\ndef solution_two(): # Implement your solution here pass test(solution_two, tests) In\u00a0[\u00a0]: Copied!
# The next line assumes your functions have a single integer as input.\ntime_functions_int([solution_one, solution_two])\n# The next line assumes your functions have a single integer as input. time_functions_int([solution_one, solution_two])
Analyse the results.
"},{"location":"essays/template-intro-programming/#your-essays-title","title":"Your essay's title\u00b6","text":"Your (and any co-author's) name, current date
"},{"location":"essays/template-intro-programming/#1-tests","title":"1 Tests\u00b6","text":"This section describes and defines the tests you will use to check your solutions. See the testing section of our guide.
"},{"location":"essays/template-intro-programming/#2-solutions","title":"2 Solutions\u00b6","text":""},{"location":"essays/template-intro-programming/#21-first-solution-name","title":"2.1 First solution name\u00b6","text":"Describe your first strategy or approach, then implement and test it.
"},{"location":"essays/template-intro-programming/#22-second-solution-name","title":"2.2 Second solution name\u00b6","text":"Describe your second strategy or approach, then implement and test it.
"},{"location":"essays/template-intro-programming/#3-performance","title":"3 Performance\u00b6","text":"This optional section compares the performance of your solutions to see which is fastest.
"},{"location":"essays/template-intro-programming/#4-concluding-remarks","title":"4 Concluding remarks\u00b6","text":"Summarise your findings and conclude which solution is best.
After completing a draft of your essay, do a final check and then see the feedback guide on how to ask for, give, and handle comments.
"},{"location":"essays/template-intro-programming/#5-acknowledgements","title":"5 Acknowledgements\u00b6","text":"Credit those who helped you create the essay. See the crediting feedback section of our guide.
"}]} \ No newline at end of file diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 751897b..5566e52 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -2,102 +2,102 @@