The perfect tutorial example?
I'm trying to come up with an example function to use in the tutorial for the parameters library. The function would ideally: * have four or fewer parameters, most of which have defaults. * have at least one defaulted parameter whose type would normally be a deduced function template parameter (when the argument is passed explicitly) * have a parameter whose default depends on the value of another parameter * have at least one parameter whose default value is of nontrivial complexity to compute (so I can demonstrate lazy defaults). * be realistic Any ideas would be most welcome. Thanks, -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jul 8, 2005, at 1:51 AM, David Abrahams wrote:
I'm trying to come up with an example function to use in the tutorial for the parameters library. The function would ideally:
* have four or fewer parameters, most of which have defaults.
* have at least one defaulted parameter whose type would normally be a deduced function template parameter (when the argument is passed explicitly)
* have a parameter whose default depends on the value of another parameter
* have at least one parameter whose default value is of nontrivial complexity to compute (so I can demonstrate lazy defaults).
* be realistic
Any ideas would be most welcome.
depth_first_search(graph, visitor, color_map, index_map) visitor has a simple default (dfs_visitor<>()) index_map has a nontrivial default of get(vertex_index, graph) color_map has a nontrivial default of: vector_property_map<color_type, typeof(index_map)> Doug
Douglas Gregor <doug.gregor@gmail.com> writes:
On Jul 8, 2005, at 1:51 AM, David Abrahams wrote:
I'm trying to come up with an example function to use in the tutorial for the parameters library. The function would ideally:
* have four or fewer parameters, most of which have defaults.
* have at least one defaulted parameter whose type would normally be a deduced function template parameter (when the argument is passed explicitly)
* have a parameter whose default depends on the value of another parameter
* have at least one parameter whose default value is of nontrivial complexity to compute (so I can demonstrate lazy defaults).
* be realistic
Any ideas would be most welcome.
depth_first_search(graph, visitor, color_map, index_map)
visitor has a simple default (dfs_visitor<>())
index_map has a nontrivial default of get(vertex_index, graph)
color_map has a nontrivial default of: vector_property_map<color_type, typeof(index_map)>
I'll try that one and see how it comes out. Thanks! P.S. I thought you had converted Boost.Graph to use Boost.Parameter, but I can't find any such code now (?) -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jul 8, 2005, at 2:50 PM, David Abrahams wrote:
P.S. I thought you had converted Boost.Graph to use Boost.Parameter, but I can't find any such code now (?)
Not yet. I'd posted a PageRank implementation using Boost.Parameter, but it required (minor) changes to the Parameter lib at that time, and I haven't tried again since. I do want to convert the Graph lib to use the Parameter lib (then it'll look like the Python bindings as well; cool!), but we just don't have the manpower right now. Doug
Douglas Gregor <doug.gregor@gmail.com> writes:
On Jul 8, 2005, at 1:51 AM, David Abrahams wrote:
I'm trying to come up with an example function to use in the tutorial for the parameters library. The function would ideally:
* have four or fewer parameters, most of which have defaults.
* have at least one defaulted parameter whose type would normally be a deduced function template parameter (when the argument is passed explicitly)
* have a parameter whose default depends on the value of another parameter
* have at least one parameter whose default value is of nontrivial complexity to compute (so I can demonstrate lazy defaults).
* be realistic
Any ideas would be most welcome.
depth_first_search(graph, visitor, color_map, index_map)
visitor has a simple default (dfs_visitor<>())
index_map has a nontrivial default of get(vertex_index, graph)
color_map has a nontrivial default of: vector_property_map<color_type, typeof(index_map)>
Say, that doesn't correspond to what I see at http://www.boost-consulting.com/boost/libs/graph/doc/depth_first_search.html and furthermore I think that last "nontrivial default" is a type, not a value. Can you clear this up? Did you mean a different algorithm? -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jul 9, 2005, at 10:38 PM, David Abrahams wrote:
Douglas Gregor <doug.gregor@gmail.com> writes:
color_map has a nontrivial default of: vector_property_map<color_type, typeof(index_map)>
Say, that doesn't correspond to what I see at http://www.boost-consulting.com/boost/libs/graph/doc/ depth_first_search.html and furthermore I think that last "nontrivial default" is a type, not a value. Can you clear this up? Did you mean a different algorithm?
I changed two things, to try to simplify the example: 1) I dropped the optional root_vertex parameter. 2) I changed the default for the color_map to something a little simpler. The real color map will be built like this: typename graph_traits<Graph>::vertices_size_type n = num_vertices(graph); std::vector<default_color_type> color_vec(n); iterator_property_map<typename std::vector<default_color_type>::iterator, IndexMap> default_color_map(color_vec.begin(), index_map); The really tough part is that color_vec needs to stick around, so it can't be buried in a function object somewhere. An equivalent (but slightly simpler) alternative is to use: typename graph_traits<Graph>::vertices_size_type n = num_vertices(graph); vector_property_map<default_color_type, IndexMap>(n, index_map); Doug
Douglas Gregor <doug.gregor@gmail.com> writes:
On Jul 9, 2005, at 10:38 PM, David Abrahams wrote:
Douglas Gregor <doug.gregor@gmail.com> writes:
color_map has a nontrivial default of: vector_property_map<color_type, typeof(index_map)>
Say, that doesn't correspond to what I see at http://www.boost-consulting.com/boost/libs/graph/doc/ depth_first_search.html and furthermore I think that last "nontrivial default" is a type, not a value. Can you clear this up? Did you mean a different algorithm?
I changed two things, to try to simplify the example:
Hmm, but any real simplification tends to confuse if the reader does what I did, and refers to the BGL docs. Anyway, suppose I want to use your simplified example. What is the *value* of the last "nontrivial default?" You wrote: vector_property_map<color_type, typeof(index_map)> but as I said, that seems to be a type!
1) I dropped the optional root_vertex parameter.
Okay.
2) I changed the default for the color_map to something a little simpler.
And impossible ;-)
The real color map will be built like this:
typename graph_traits<Graph>::vertices_size_type n = num_vertices(graph); std::vector<default_color_type> color_vec(n); iterator_property_map< typename std::vector<default_color_type>::iterator, IndexMap
default_color_map(color_vec.begin(), index_map);
The really tough part is that color_vec needs to stick around, so it can't be buried in a function object somewhere.
Well, you can have it in a function object, as long as there's a way to retrieve it, or the function object outlives the function call. But more to the point, shouldn't it be part of the color_map itself? There's no rule that the color_map has to be a simple vector, is there?
An equivalent (but slightly simpler) alternative is to use:
typename graph_traits<Graph>::vertices_size_type n = num_vertices(graph); vector_property_map<default_color_type, IndexMap>(n, index_map);
Yes, that looks simpler, because it avoids the issue of holding onto a separate color_vec. Is there some downside? -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jul 10, 2005, at 8:50 AM, David Abrahams wrote:
Douglas Gregor <doug.gregor@gmail.com> writes:
The real color map will be built like this:
typename graph_traits<Graph>::vertices_size_type n = num_vertices(graph); std::vector<default_color_type> color_vec(n); iterator_property_map< typename std::vector<default_color_type>::iterator, IndexMap
default_color_map(color_vec.begin(), index_map);
The really tough part is that color_vec needs to stick around, so it can't be buried in a function object somewhere.
Well, you can have it in a function object, as long as there's a way to retrieve it, or the function object outlives the function call. But more to the point, shouldn't it be part of the color_map itself? There's no rule that the color_map has to be a simple vector, is there?
No, color_map can be any property map from vertices to color values. We just tend to build them as vectors because it's a convenient storage mechanism.
An equivalent (but slightly simpler) alternative is to use:
typename graph_traits<Graph>::vertices_size_type n = num_vertices(graph); vector_property_map<default_color_type, IndexMap>(n, index_map);
Yes, that looks simpler, because it avoids the issue of holding onto a separate color_vec. Is there some downside?
There's a little more overhead to a vector_property_map than an iterator_property_map<vector iterator, ...>, because the vector_property_map goes through a shared_ptr. I don't know if it has a measurable effect. Doug
David Abrahams <dave@boost-consulting.com> writes:
Anyway, suppose I want to use your simplified example. What is the *value* of the last "nontrivial default?"
You wrote:
vector_property_map<color_type, typeof(index_map)>
but as I said, that seems to be a type!
No reply? -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jul 10, 2005, at 11:30 AM, David Abrahams wrote:
David Abrahams <dave@boost-consulting.com> writes:
Anyway, suppose I want to use your simplified example. What is the *value* of the last "nontrivial default?"
You wrote:
vector_property_map<color_type, typeof(index_map)>
but as I said, that seems to be a type!
No reply?
I gave the value in my other reply: The type is above; given n = num_vertices(graph), the default value of color_map is: vector_property_map<default_color_type, typeof(index_map)>(n, index_map); Doug
Douglas Gregor <doug.gregor@gmail.com> writes:
On Jul 10, 2005, at 11:30 AM, David Abrahams wrote:
David Abrahams <dave@boost-consulting.com> writes:
Anyway, suppose I want to use your simplified example. What is the *value* of the last "nontrivial default?"
You wrote:
vector_property_map<color_type, typeof(index_map)>
but as I said, that seems to be a type!
No reply?
I gave the value in my other reply: The type is above; given n = num_vertices(graph), the default value of color_map is:
vector_property_map<default_color_type, typeof(index_map)>(n, index_map);
Thanks; I missed that. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams <dave@boost-consulting.com> writes:
Douglas Gregor <doug.gregor@gmail.com> writes:
Say, that doesn't correspond to what I see at http://www.boost-consulting.com/boost/libs/graph/doc/depth_first_search.html and furthermore I think that last "nontrivial default" is a type, not a value. Can you clear this up? Did you mean a different algorithm?
A note about the graph library named parameter doc format: it's almost inscrutable, and it puts the elements in an order that doesn't correspond to their relative emphasis. For example: IN: vertex_index_map(VertexIndexMap i_map) - You start with the I/O role of the parameter, and CAPITALIZE IT, no less! That's the most visible thing on the line, and the word that lines up horizontally from parameter to parameter. You should be showing the parameter name first, and probably in bold. People get a very strong idea of the meaning of a parameter from its name, at least if the name is well-chosen. - What I see above, after "IN," looks like a function declaration. - Which is the name of the parameter, "vertex_index_map" or "i_map?" I'm guessing i_map is an internal name and could be dropped, and vertex_index_map is the name of the function (or member of bgl_named_params<>) that you call. - Ooooh, now it all begins to be clear. Still, it took me a long time, though. I presume this will _need_ to be changed when you start using Boost.Parameter, since the primary interface won't have anything to do with functions. - Anyone not using the named parameter interface still needs to read these descriptions to understand the defaults they get for the positional overloads, so they are forced to understand bgl_named_params in order to get started. -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jul 10, 2005, at 9:35 AM, David Abrahams wrote:
David Abrahams <dave@boost-consulting.com> writes: A note about the graph library named parameter doc format: it's almost inscrutable, and it puts the elements in an order that doesn't correspond to their relative emphasis. For example: [snip good criticisms]
You're absolutely correct, but we're not going to fix that now :) When we move to using the Parameter library---which I hope to do in stages soon after 1.33.0 is released---we'll need to update the documentation style for the BGL algorithms. I also hope to switch to Quickbook for the documentation and figure out how to integrate the Python bindings better. Perhaps we could build docstrings from the Quickbook source, so that all of the BGL-Python documentation is accessible from within Python, and generated from the same source? I appreciate your comments on the documentation, and will try to take them into account when we redesign the BGL algorithm documentation for the Parameter lib. Doug
participants (3)
-
David Abrahams -
Doug Gregor -
Douglas Gregor