Skip to content

Conversation

@RaoulLuque
Copy link
Member

This should fix #637.

I tried my best to deduce the iteration order from the code and various tests. It should also be considered, whether one actually wants to "fix" the iteration order in the docs of the respective methods. That is, whether there should be a guarantee for the user that this iteration may not change in the future.

Another possibility would be to add the iteration order, as suggested in this PR with a warning that this iteration might change in the future.

On a similar note, would it make sense to create tests that check whether this guarantee holds, to make sure that, also in the future, the docs of the methods actually reflect the reality?

@RaoulLuque RaoulLuque changed the title Docs: Specify iteration order for neighbors and edges and their variants docs: Specify iteration order for neighbors and edges and their variants May 18, 2025
@starovoid starovoid requested review from ABorgna and starovoid May 18, 2025 18:11
@starovoid starovoid added this to the 0.8.2 milestone May 18, 2025
@starovoid
Copy link
Collaborator

Hi, please also fix clippy warnings

@RaoulLuque
Copy link
Member Author

RaoulLuque commented May 18, 2025

Hi, not entirely sure, but the clippy errors don't seem to stem from my changes. Therefore I am not sure how to fix them ? Could there be an issue with clippy/rust nightly ?

Or do you mean that I should change the code snippets that clippy is showing even though they don't have any immediate connection to my PR?

@starovoid
Copy link
Collaborator

I fixed the warnings in #791, now everything should be fine.

@starovoid
Copy link
Collaborator

starovoid commented May 31, 2025

It also took me a long time to overread the code, but it seems to me that you have written everything correctly. The iteration order is something that may change one day in the future, but since users prefer to see a note about the iteration order, we really should make some efforts to maintain clarity.

So (to prove the words about the iteration order), I suggest writing the some tests:

  1. one small test for each case;
  2. randomized tests for each case on graphs with ~20 vertices and ~20-200 edges (including multiple edges and loops).

Since this is a fairly large job, I will transfer this PR to milestone 0.8.3.

@starovoid starovoid marked this pull request as draft May 31, 2025 13:42
@starovoid starovoid modified the milestones: 0.8.2, 0.8.3 May 31, 2025
@RaoulLuque
Copy link
Member Author

Yes, that is a good idea :) I will add those tests then and reopen the PR once they are done 👍

Could you maybe specify a bit more what you had in mind for the randomized tests? Just to make sure that I include everything you are imagining :)

@starovoid
Copy link
Collaborator

Could you maybe specify a bit more what you had in mind for the randomized tests?

I mean the tests where we create a graph and remember the order of edge insertion, then iterate over the edges/neighbors comparing the orders. Repeat each such check several times, processing a new random graph each time.
To generate random graphs, there are functions in petgraph or graphalgs. Feel free to adopt it.

@RaoulLuque
Copy link
Member Author

Okay, I see, I am just hesitant with combining the randomness and remembering the order of edge insertion, but I'll work something out I guess 👍

@starovoid starovoid added A-documentation Area: Docs S-in-progress Status: This issue is being worked on labels Jun 13, 2025
@RaoulLuque RaoulLuque added S-waiting-on-author Status: Awaiting some action by the PR/Issue author and removed S-in-progress Status: This issue is being worked on labels Jun 22, 2025
@RaoulLuque RaoulLuque added S-waiting-on-review Status: Awaiting review from the assignee but also other interested parties and removed S-waiting-on-author Status: Awaiting some action by the PR/Issue author labels Jul 28, 2025
@RaoulLuque
Copy link
Member Author

RaoulLuque commented Jul 28, 2025

Okay, so I added unit tests for Graph and StableGraph, both directed and undirected. I tried to come up with Quickchecks, but nothing seemed very sensible in my opinion.

The problem being that one does not know what edges the arbitrary graph has. And this will definitely influence the order in which neighbors may appear in the different iterators. I tried adding fixed edges to the arbitrary graphs and then checking their order, but these edges might already exist which would confuse the ordering. Of course, one could select certain pairs of nodes, remove existing edges between them and then add edges there and check their order, but at that point it seems somewhat useless to use quickcheck in the first place 🤔

What do you think @starovoid ? Do you have a specific idea on how the quickchecks should look like or would you also be fine with "just" having unit tests, which test for the iteration order of the different functions ?

@RaoulLuque RaoulLuque marked this pull request as ready for review July 28, 2025 15:29
@starovoid
Copy link
Collaborator

What do you think @starovoid ? Do you have a specific idea on how the quickchecks should look like or would you also be fine with "just" having unit tests, which test for the iteration order of the different functions ?

Hi! Unit tests look great, I think it makes no sense to overcomplicate the task using quickcheck.
+1330 lines of code, I'm impressed 😃

Copy link
Collaborator

@starovoid starovoid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me

@RaoulLuque
Copy link
Member Author

Oops, just messed something up with the rebase I guess 🤔

# Conflicts:
#	src/graph_impl/mod.rs
#	tests/stable_graph.rs
@RaoulLuque
Copy link
Member Author

This is failing because of #878, could you have a look at the other PR such that we can fix the errors in our CI @starovoid :)?

@RaoulLuque RaoulLuque added this pull request to the merge queue Sep 21, 2025
Merged via the queue into petgraph:master with commit 0a0efbe Sep 21, 2025
15 of 20 checks passed
@RaoulLuque RaoulLuque deleted the iteration_order branch September 21, 2025 18:21
@github-actions github-actions bot mentioned this pull request Sep 21, 2025
github-merge-queue bot pushed a commit that referenced this pull request Sep 30, 2025
## 🤖 New release

* `petgraph`: 0.8.2 -> 0.8.3 (✓ API compatible changes)

<details><summary><i><b>Changelog</b></i></summary><p>

<blockquote>

##
[0.8.3](https://github.com/petgraph/petgraph/compare/petgraph@v0.8.2...petgraph@v0.8.3)
- 2025-09-28

### Bug Fixes

- Infinite `subgraph_isomorphisms_iter` for empty isomorphisms
([#780](#780))
- Algos don't work on `UndirectedAdaptor`
([#870](#870))
([#871](#871))
- use a queue for SPFA
([#893](#893))
- `StableGraph::reverse` breaks free lists
([#890](#890))

### Documentation

- Fix examples link in README and unify typesetting of one word
([#823](#823))
- Add link to multigraph definition to isomorphism algos
([#824](#824))
- Fix auxiliary space (and time) complexity of bron-kerbosch
([#825](#825))
- Fix Typo in Operator Module Documentation
([#831](#831))
- Sync the crate feature flags in the README and docs
([#832](#832))
- Remove all \[Generic\] tags from algo docstrings
([#835](#835))
- Fix typos in comments
([#836](#836))
- Revamp CONTRIBUTING.md
([#833](#833))
- Update `GraphMap` link in README
([#857](#857))
- Add doc comment for `Dot::with_attr_getters`
([#850](#850))
- Specify iteration order for neighbors and edges and their variants
([#790](#790))
- Collection of Doc fixes
([#856](#856))

### New Features

- Add `into_nodes_edges_iters` to `StableGraph`
([#841](#841))
- Add methods to reserve & shrink `StableGraph` capacity
([#846](#846))
- Add Dinic's Maximum Flow Algorithm
([#739](#739))
- make Csr::from_sorted_edges generic over edge type and properly
increase edge_count in Csr::from_sorted_edges
([#861](#861))
- Add `map_owned` and `filter_map_owned` for `Graph` and `StableGraph`
([#863](#863))
- Add dijkstra::with_dynamic_goal
([#855](#855))
- Fix self-loop bug in all_simple_paths and enable multiple targets
([#865](#865))
- mark petgraph::dot::Dot::graph_fmt as public
([#866](#866))
- Add bidirectional Dijkstra algorithm
([#782](#782))

### Performance

- Make A* tie break on lower h-values
([#882](#882))

### Refactor

- add examples for scc algorithms and reorganize into dedicated module
([#830](#830))
- Remove unnecessary trait bounds from impls/methods
([#828](#828))
- replace uses of 'crate::util::zip' with 'core::iter::zip'
([#849](#849))
- Fix clippy (and other) lints
([#851](#851))
- Cleanup repo ([#854](#854))
- replace crate::util::enumerate with Iterator::enumerate
([#881](#881))

### Testing

- Add dependency list for 'quickcheck' feature
([#822](#822))
- Fix feature cfg capitalization in doctest
([#852](#852))
</blockquote>


</p></details>

---
This PR was generated with
[release-plz](https://github.com/release-plz/release-plz/).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Egor Starovoitov <52821033+starovoid@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-documentation Area: Docs S-waiting-on-review Status: Awaiting review from the assignee but also other interested parties

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document iterating order

2 participants