Rjf/dispatcher req sort

[robfitzgerald]

@nreinicke i think i found it. i was writing an email response to dylan and was jotting down some potential leads, like looking into whether scipy guarantees the linear_sum_assignment is deterministic. then i was like OH YA i should quadruple-check that we build the matrix deterministically. we do not.

in the dispatcher logic, we were creating the assignment matrix of available vehicles by current unassigned requests. the unassigned_requests collection was being sorted by value descending, which is to say, "put the highest-valued customers at the top of this list". but there was no tie-breaker:

            unassigned_requests = simulation_state.get_requests(
                sort_key=lambda r: -r.value,
                filter_function=_valid_request,
            )

I fixed this by making the sort key lambda r: (-r.value, r.id). I ran manhattan.yaml twice in a row and observed the top-level stats were the same:

as you'll see in the changed files for this PR, i've also updated the newly-added design.md section of the HIVE documentation to clearly highlight the sort issue.

[robfitzgerald]

read the docs failed with the following error (below). link to build. it looks like we need to pin our sphinx version to "<7.0.0" as readthedocs doesn't support sphinx 7 yet.

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 1093, in handle_page
    output = self.templates.render(templatename, ctx)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/readthedocs_ext/readthedocs.py", line 181, in rtd_render
    content = old_render(template, render_context)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/jinja2glue.py", line 196, in render
    return self.environment.get_template(template).render(context)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/themes/basic/page.html", line 10, in top-level template code
    {%- extends "layout.html" %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx_rtd_theme/layout.html", line 23, in top-level template code
    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
jinja2.exceptions.UndefinedError: 'style' is undefined

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 294, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 361, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 569, in write
    self._write_serial(sorted(docnames))
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 579, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 667, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/nrelhive/envs/206/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 1100, in handle_page
    raise ThemeError(__("An error happened in rendering the page %s.\nReason: %r") %
sphinx.errors.ThemeError: An error happened in rendering the page autoapi/index.
Reason: UndefinedError("'style' is undefined")

Theme error:
An error happened in rendering the page autoapi/index.
Reason: UndefinedError("'style' is undefined")

[nreinicke]

Dude! Great find! It would have taken me forever to track that down. So happy you had the lighting bolt moment ⚡