Computer science: Add new graphs project

[damon314159]

Because

The concept of graphs is introduced but rather swept under the rug in the current implementation of the knight travails project

This PR

• Introduces a new project to go between BST and KT projects in the computer science section of both pathways.
• Edits the existing KT project to make back-references to this project instead of introducing graphs haphazardly itself.

Issue

Closes #28487

Additional Information

Notes:

• This is currently the first draft of this project. I have not yet translated it to Ruby, or edited the KT project as described in the "this PR" section. I want to get maintainer input on the substance of the project before proceeding with those two steps, since there are almost certainly changes that need to be made to this draft.
• I've opted to keep the implementation as simple as possible. No specific mention of edge cases to be considered, no weighted or directed edges, and no dedicated Vertex wrapper class (though I do mention that this is a possibility later on in the project). I think what is here is plenty for the learner to understand the motivations and produce a basic implementation, without spending ages on niche aspects.
• I included no methods regarding traversals or searching, since those concepts are introduced in the previous BST project, and are tied into the graphs with the subsequent KT project
• I don't know how to either declare where the lesson should sit in the curriculum, nor how to add images to a lesson page 😅 . I might need some guidance on that once this gets through the drafting process.
• I went ahead and produced a solution that's something like what I imagine learners would produce for this project. You can see it in this gist if you're curious what this might be like.

Pull Request Requirements

• I have thoroughly read and understand The Odin Project curriculum contributing guide
• The title of this PR follows the location of change: brief description of change format, e.g. Intro to HTML and CSS lesson: Fix link text
• The Because section summarizes the reason for this PR
• The This PR section has a bullet point list describing the changes in this PR
• If this PR addresses an open issue, it is linked in the Issue section
• If any lesson files are included in this PR, they have been previewed with the Markdown preview tool to ensure it is formatted correctly
• If any lesson files are included in this PR, they follow the Layout Style Guide

[JoshDevHub]

@damon314159 Thanks for making this PR!

My initial impression of this is good. I did wonder why you ask for an adjacency matrix over an adjacency list? A list would be more convenient (or equivalently convenient) for nearly every operation, and I suspect learners who've been formally exposed to this will bring that up.

[damon314159]

@damon314159 Thanks for making this PR!

My initial impression of this is good. I did wonder why you ask for an adjacency matrix over an adjacency list? A list would be more convenient (or equivalently convenient) for nearly every operation, and I suspect learners who've been formally exposed to this will bring that up.

It wasn't a decision I put a lot of weight on. I mostly went with a matrix so that it was easily displayable. I don't object to switching to a list approach, but it does increase the complexity of the visualisation

[JoshDevHub]

Visualization is a good point, and I think some of the inconveniences with adding and removing vertices and edges make for good practice with keeping state held between multiple structures in-sync.

I could probably be onboard for a matrix, but I think it could be good to potentially talk a bit more about a list and maybe recommend using that in Knight Travails?

[damon314159]

Sorry I left this hanging for so long! I completely forgot about it.
Implemented your feedback @JoshDevHub

[JoshDevHub]

Sorry for taking a bit to look back at this @damon314159 I'm still potentially interested in including this, but I want to discuss some things with the team first.

I'm a bit wary on the scope of the project gauntlet of Linked List > Hash Map > Binary Search Tree > Knight Travails, and this will be another project to add to that bit. But I also think expanding the quality of the graph instruction would be nice for helping with Knight Travails and giving learners a better foundation in that area.

I'll get back to you after I've discussed more.

[JoshDevHub]

Okay gonna shift my above concerns to another issue and begin reviewing this in earnest this week because I think it's a good idea. Thank you for your patience 🙌

[JoshDevHub]

This is really good I think. One of the main things to figure out would be the image. Let me know if you have any questions about that.

I think the content all makes really good sense here. I might get another, less DSA-oriented maintainer to look this over and see if it's clear from that perspective.

I'll also try to put together a solution myself over the weekend and see how it feels.

Let me know if you have any other comments/concerns @damon314159

[JoshDevHub]

Feel free to draw up a concrete example here. Should be able to just throw together something simple using excalidraw.

You can find out how to add images to the curriculum through the contributing guide.

[damon314159]

Will get something worked out this evening

[damon314159]

How's this?

[scriabin-enjoyer]

Hi, great work @damon314159 . Although I am not involved with this PR in any way, I was looking at it and just wanted to offer my perspective on some things I noticed.

In particular, neither the project description nor the G4G article explains why one might use an adjacency list vs an adjacency matrix, and in the case of the matrix, why it is even useful to represent a graph as a matrix in the first place. This latter point about matrices also has implications regarding getNeighbours and getCommonNeighbors functions, and this is especially important in the case of directed graphs.

And moreover, unless learners have had exposure to matrices before (via calculus/linear algebra course), you can't really appreciate all the nice things that matrices can tell you about the underlying data.

This is all to say that I think adjacency lists are a much more motivating representation, as one wouldn't need an intuition about matrices to actually reason about their usefulness and applicability.

[damon314159]

@scriabin-enjoyer do you have an idea how we could do some kind of visualisation for that?

While not necessary I think it adds a layer of tangibility that many learners will appreciate if there is some kind of visual

[scriabin-enjoyer]

@damon314159 Yeah there are several options. The G4G article linked does provide a graphical representation see here.

Typically (in my experience) people usually represent adjacency lists as associative arrays with the keys being the nodes of the graph and the values are arrays or linked lists containing nodes that are adjacent to the key. Such a textual representation would be imo a legitimate replacement for the printMatrix command, as in the attached screenshot, which shows a network example. Is something like this what you were looking for?

Edit: Additionally, here is a re-work of your printMatrix function that prints the adjacency list, with a similar output as in the linked list project

function printAdjacencyList(graph) {
  for (const vertex in graph.adjList) {
    const neighbours = graph.adjList[vertex].map(v => `( ${v} )`).join(' -> ')
    console.log(`${vertex}: ` + neighbours);
  }
}

It's especially nice for directed graphs. It will print something like the following (for an undirected mesh topology with 3 vertices):

x: ( y ) -> ( z )
y: ( x ) -> ( z )
z: ( x ) -> ( y )

[JoshDevHub]

After thinking about this some more, I also think an adjacency list would be the better approach to show. We can figure something out for generating a nice visual (something to similar to what @scriabin-enjoyer posted seems fine enough to me)

I think the matrix representation is a bit more difficult to reason through for someone new to graphs and without any prior math or CS experience around such concepts. It also very much simplifies things like adding new vertices or adding new neighbors and so on. I think the matrix representation is cool in the sense that you have to keep multiple structures in-sync, but I've become drawn to the specter of simplicity regarding the DSA topics over time. Especially since I'm one of the main people maintaining it and dealing with people's problems and issues 😅

If you feel strongly it should be a matrix though, we could talk about it some. I almost feel like if we go that route, we may want a graph lesson that goes more into it, adjacency lists, and the situations where a developer may use one vs. the other.

Anyways, let me know what you think @damon314159

[JoshDevHub]

Basically everything else about this is good to go I think. So if we can figure this bit out, I think this could come together and be pushed into the curriculum pretty soon.

[JoshDevHub]

Any further input for this @damon314159 ? No rush or anything, just curious where you're at re: my last messages.

Another thing that might be of interest is this #30512

TLDR: we plan to move the testing sections ahead of the CS section and then require learners to test the projects in the CS section. Should this project be accepted, I'd want to do the same with it. This should make it less of a requirement to have a pretty console output of the graph, as learners would be expected to test their implementation rather than manually running operations and checking stdout.

But yeah. Let me know what you think.

[damon314159]

Hi @JoshDevHub maybe this is something @scriabin-enjoyer can take over from me if they're willing?

Not sure I've got capacity to make the changes and/or add tests as it stands. I recognise this project has been collecting dust for a while now

[JoshDevHub]

@damon314159 Thanks for letting me know. And of course thank you for all the work you've put into this so far and for having the idea in the first place.

@scriabin-enjoyer Would you want to take ownership of this PR from here? If not, that's perfectly fine, and I can probably even take it myself. Just checking if you have any interest.

[scriabin-enjoyer]

Hi @JoshDevHub , Yeah I can take this on. A few questions:

1. Considering JS and Ruby Courses: Require learners to write tests for the projects in the Computer Science section #30512 :
   should we add this graph-project first, so that you can then include this graph-project as part of the linked testing epic-PR ? If so, then I just want to confirm that we should leave in the "Test your Graph" section. Or do you have something else in mind for dealing with this?
2. Regarding the image, I do like the idea of a computer network example because I like networks and they are comprehensible for most people. If you think this is fine, then I'll make a nicer image than the one above and we can use that. Otherwise, I am open to suggestions.
3. Can you verify my understanding of the "add new lesson" workflow:
   1. Make a curriculum PR for the lesson content (i.e. finalize this PR)
   2. Make a curriculum PR for the image
   3. Make a website PR according to the contributing guide
4. Concerning the graph interface of Damon's current draft: I noticed there are no traversal methods and no path-finding methods. Should learners be required to implement either of these?
   I am thinking that they should, because these operations are what make graphs much more useful, and the project in its current state is actually somewhat trivial compared to the other DSA projects (especially using an adjacency list). I do understand that the purpose of Knight's Travails is for learners to think about BFS/DFS in the KT context and to implement it themselves. I was thinking it might be good to (at the very least) add a find_path(x, y) method that returns a (not necessarily shortest) path from x to y if it exists, or maybe even a predicate path?(x, y) — in this way, learners will get to practice actually walking a graph. Please let me know your thoughts — especially since this has some consequences regarding the discussion in Knights Travails: Clarify BFS for grids in Knight’s Travails #29783.
5. Let me know if you have any other guidance or important notes for me (Sorry I know I asked a lot of questions 😅 Thanks in advance!)

@damon314159 thanks very much for all the work you've done already, I think you've done all the hard parts of it so getting this merged shouldn't be too painful (...i think lol). I would value any insight you have going forward if you notice anything important to share.

[JoshDevHub]

Thank you for agreeing to pick this up @scriabin-enjoyer

1. Considering JS and Ruby Courses: Require learners to write tests for the projects in the Computer Science section #30512 :
   should we add this graph-project first, so that you can then include this graph-project
   as part of the linked testing epic-PR ? If so, then I just want to confirm that we should
   leave in the "Test your Graph" section. Or do you have something else in mind for dealing with this?

I'll think more about this as it gets closer to merging. If we already have the other stuff done or mostly done, it may make sense to go ahead and remove the "Test your Graph" thing and add a little information about writing automated tests for this project. If the other stuff isn't close to being done though and this becomes ready to merge, we can leave that section alone.

So for a direct answer: just leave that section in for now.

2. Regarding the image, I do like the idea of a computer network example because
   I like networks and they are comprehensible for most people. If you think this is fine,
   then I'll make a nicer image than the one above and we can use that. Otherwise, I am open to suggestions.

I think a computer network is a good illustration.

3. Can you verify my understanding of the "add new lesson" workflow:

   1. Make a curriculum PR for the lesson content (i.e. finalize this PR)
   2. Make a curriculum PR for the image
   3. Make a website PR according to the contributing guide

This sounds correct. Note that we can accept and fully merge the first two PRs without any effects on the site (and we probably will do just that).

Also note that you can add (and should) add the image files to this PR. The PR for the image should just be to replace direct links to the images in the lesson content with CDN links (better performance around the world). You can see more about that here (it says you need two PRs, but you can just include the image files with this one and that's fine).

Concerning the graph interface of Damon's current draft: I noticed there are no traversal methods
and no path-finding methods. Should learners be required to implement either of these?
I am thinking that they should, because these operations are what make graphs much more useful,
and the project in its current state is actually somewhat trivial compared to the other DSA projects
(especially using an adjacency list). I do understand that the purpose of Knight's Travails is for learners
to think about BFS/DFS in the KT context and to implement it themselves. I was thinking it might be
good to (at the very least) add a find_path(x, y) method that returns a (not necessarily shortest) path
from x to y if it exists, or maybe even a predicate path?(x, y) — in this way, learners will get to
practice actually walking a graph. Please let me know your thoughts — especially since this has some
consequences regarding the discussion in Knights Travails: Clarify BFS for grids in Knight’s Travails #29783.

I like the path? idea a lot actually. I'd probably gladly accept something along those lines that keeps it fairly simple/constrained.

[JoshDevHub]

Superseding this with #30700