JOSS REVIEW. DOCUMENTATION: In-depth Use

[torressa]

From https://github.com/openjournals/joss-reviews/issues/1655#issuecomment-523107985

• [x] I'd also like to more in-depth use of this software. Right now, I can only see some toy examples in the docstrings. Ideally, I think this would be best with an example with real data.

One question I have: how are constraints from real problems coded in cspy? I know cspy can be used in the vehicle routing problem with time windows (desaulniers2008tabu), but don't know how to code the time constraints in cspy.

Answer: Will be clear with a working example

[stsievert]

Here's the information I see in different examples:

• https://cspy.readthedocs.io/en/latest/how_to.html
  • How to create a graph w/ Networkx
  • How to create an additive resource extension functions (REFs) (but not how to use it, or when it's useful)
• Docstrings (e.g., https://cspy.readthedocs.io/en/latest/api/cspy.PSOLGENT.html)
  • How to get a path from an algorithm

I'd like to see an in-depth use, preferably with real data. With the graph, how would I specify the weights, REFs and max_res/min_res? What are the tradeoffs between algorithms?

[torressa]

I've included an example for some ongoing work using column generation. Unfortunately, I haven't managed to come up with a simpler example.

[stsievert]

I think the example previously in the paper ("Jane is part-time postwoman working ...") is a great example. I'd love to see that in the documentation.

And :+1: for adding the airport example!

[torressa]

Cool, thanks for the feedback!.. I thought the Jane the postwoman was a bit too simplistic. Will do that then :)

[stsievert]

I’m a fan of simple. It’ll lower the barrier to understanding the software.

I’m also a fan of the in-depth airport example. It helps readers who know the math and what they’re doing understand the software, and see some more advanced uses.

[torressa]

Closing for now.

[torressa]

Reopened, add simple example. https://github.com/openjournals/joss-reviews/issues/1655#issuecomment-598995867

[torressa]

Added simple example that used to be in the paper as a jupyter notebook.

[stsievert]

Thanks for the simple example at https://cspy.readthedocs.io/en/latest/how_to.html#simple-example. That clears up a lot of the usage.

We have to transform the network for one compatible with cspy. To do this suppose we have two functions from jpath_preprocessing that perform all the changes required (for more details, see jpath)

This seems important enough that a description should be included in the example. It could be short, maybe only a sentence. I'd like for the user to better understand the requirements.

Maybe something like this?

We have to transform the network for one compatible with cspy, as per the Input requirements. The following code will convert a city map into a directed graph, rename the start/end nodes of Janes walk to be Source and Sink (names which cspy uses), and calculate the specifics of Jane's walk (figuring out travel time, adding buildings/sights, etc).

from networkx import DiGraph

# Transform M to comply...
G = DiGraph(M, directed=True, n_res=5)

# Relabel nodes the start/end nodes as source/sink
 G = jpath_preprocessing.relabel_source_sink(G, {"Source": "Ternatestraat", "Sink": "Delftweg"})

# Figure out details of Jane's walk
 G = jpath_preprocessing.add_cspy_edge_attributes(G)

[torressa]

Updated! Thanks for the suggestion :)