radar-research-lab
Modernize Documentation Site
This is a follow-on to #50.
The main objective is to make our documentation site more modern and easier to read. You can view the proposed documentation site from the GH Actions below.
Since this PR builds on #50, the diff compared to main will be hard to review. I suggest we merge #50, and then can revisit this PR for discussion.
@AnranHu I'm pasting your comments here so we can track the changes.
Quickstart
- [x] A MFG —> An MFG…
Formal
- [x] add introduction of notation \Delta
- [x] check index of time : T or T+1
- [x] check notation: T or \mathcal{T}, S or \mathcal{S}
- [x] present tense or past tense: Note if every agent followed policy pi it would induce a mean-field denoted by
I've added a line clarifying what $X^Y$ means for two finite sets $X$ and $Y$ which should resolve the middle two points.
Exploitability
- [x] a policy pi —> a policy \pi
- [x] add some explanations to L^\pi, give a reference to MFOMO
Algorithms
- [x] for all algorithms, add reference right after the names of the algorithms
- [x] give a summary/table of contents at the beginning of all algorithms
Fictitious Play
- [x] mention the range of alpha
MF-OMO
- [ ] hat initialization true by default?
- [x] You can also apply different norm to the objective terms.” a lot of typos here, for l2 and l1-l2
Regarding hat initialization, do you prefer to have hat_init=True be the default?
MF-OMI
- [x] explanation is not accurate
User-Defined
- [x] add a very simple example or an abstract update rule of \pi
Tuning
- [x] the “stat-“ and “The statstic …” should be on the same line, both for FailureRate and GeometricMean
User-Defined
- [x] add an (very simple or trivial) example, currently the explanation is not clear enough
Examples
- [x] explain what verbose means
Example 2
- [ ] OMI fails before tuning? maybe change the default value of alpha of OMI. Show a different example on tuning here, maybe prior descent.
Isn't the point here to show that at first the algorithm fails, and then after tuning it performs nicely?
References
- [x] we only have 5 references? cite all related papers
@matteosantama Thanks for the edits! Btw is there a way to see the updated website? Seems that https://mfglib--51.org.readthedocs.build/en/51/ is still the initial version when the PR was created, making it a bit inconvenient to check the updated version.
@junziz I think it's a caching issue. Try opening the site in an incognito window
Regarding hat initialization, do you prefer to have hat_init=True be the default?
Yes in general we have found hat initialization to be helpful so it might be better to have the users use this by default instead of needing to dig into the doc to find this knob.
Isn't the point here to show that at first the algorithm fails, and then after tuning it performs nicely?
Oh I think the point here is that 1) we should probably re-pick the default parameters of all the algorithms so that they work for at least some environments (with their default sizes and parameters) that we have already prepared in the library if not most/all of them; 2) we then show an example where our default choice does not work and need tuning. For 1), for example, we should probably set alpha in MF-OMI to be default to 0.1 or 0.01 or even 0.001; the current default 1 is something we blindly picked initially but turned out to be not working for nearly all of the algorithms and so is not even a meaningful non-tuned baseline. Similarly for OMD, FP, etc. For 2), let's just add some more algorithms to show the effect of tuning here instead of giving users a (wrong) impression of MF-OMI is the (only) algorithm that needs tuning/benefits from tuning.
Btw on a related point, let's add from_study in the API description of tuning, which is currently missing.
I think it's a caching issue. Try opening the site in an incognito window
Yes it's temporary and should be caching issue. Thanks!
Perhaps this closes https://github.com/radar-research-lab/MFGLib/issues/7?
Yeah mostly, except that 1) we currently don't mention the problem parameters of environments APIs in the doc, and we'd better at least add links to the source code of these environments in the doc; 2) some of my comments about poetry install/uninstall/reinstall. For 2), another related thing I found recently is that it seems that we need to ensure the (pre-installed) python version to be not too new in order for the poetry install to work; like I found 3.13 leads to some failures while 3.9 does not. I think this is very case by case but it I think it would be helpful to add some tips about e.g., the best practice is to keep a minimal virtual env without any preinstalled packages including python itself but just poetry, or use something like micromamba to create some minimal env like micromamba create -n mfglib_202505 -c conda-forge python=3.9 poetry with not a too new python (and if encountering conflict stuff, just try to move to python 3.9 and also minimize installing any packages in the env before running poetry install) in the CONTRIBUTING.md, etc.
@matteosantama
Regarding poetry, I don't think we should document the tool beyond the absolute basics. It is better to refer contributors to the official poetry documentation, where they can learn about more advanced usage.
Excepting advanced usage, poetry install is the only command our contributors should need. I'm not sure I understand your questions about "poetry uninstall". As far as I'm aware, such a command is non-existent and unnecessary. Perhaps you could elaborate on what you are trying to achieve with such a command?
Can you share the error message you encounter with Python 3.13? MFGLib itself only requires Python>=3.9 but it is possible that one of our dependencies demands Python<3.13, in which case Poetry is behaving as expected.
@junziz I believe I've addressed most of your comments with the latest commits. Let me know what you think.
If you want to change the default parameters for the algorithms so that they generally work across many environments, let's open a new issue and address that separately. It's probably better for us to keep this PR as single-focused as we can.
Regarding poetry, I don't think we should document the tool beyond the absolute basics. It is better to refer contributors to the official poetry documentation, where they can learn about more advanced usage.
Yeah agree. It makes more sense to just resolve the problems as much as possible on our end automatically, instead of mentioning tips for resolving these on users' end which would be in general only confusing.
Excepting advanced usage, poetry install is the only command our contributors should need. I'm not sure I understand your questions about "poetry uninstall". As far as I'm aware, such a command is non-existent and unnecessary. Perhaps you could elaborate on what you are trying to achieve with such a command?
I just meant some situations in which a user wants to uninstall MFGLib and the associated poetry installed packages to restore a clean status and then e.g., install a new version of MFGLib. The reason for such uninstall/reinstall could be typically due to previous package somehow broken/not working. It is not essential as the user could just create a new and clean virtual env for this purpose. So agree we don't need to mention/emphasize this as it's common sense and particularly not specific/directly related to MFGLib anyway.
Can you share the error message you encounter with Python 3.13? MFGLib itself only requires Python>=3.9 but it is possible that one of our dependencies demands Python<3.13, in which case Poetry is behaving as expected.
Don't recall the exact message right now, but I do think we should probably just directly specify in pyproject.toml to use exactly python 3.9 to avoid such unnecessary nuances on user's end?
I believe I've addressed most of your comments with the latest commits. Let me know what you think.
Yes! Thanks for all the improvements! They look great! Particularly, the enrichment of the environments descriptions in the doc is great and the automethod approach also makes it easy to maintain in the future which is really nice :)
If you want to change the default parameters for the algorithms so that they generally work across many environments, let's open a new issue and address that separately. It's probably better for us to keep this PR as single-focused as we can.
No we don't need these for now. Your changes associated with MF-OMI in terms of changing the default alpha and updating the examples page to now showing it by default works but tuning improves it is good enough. Thanks!
I believe I've fixed the issue with the Python versions.
Since we had specified python_version>=3.9, Poetry identified scipy==1.13.1 as the version to install (later versions of scipy were ruled out since they require python_version>=3.10).
However, scipy==1.13.1 does not provide a wheel for Python 3.13 so Poetry then attempted to build it from source. Building scipy from source is a complicated process that requires careful configuration, and it was failing.
The solution is to include additional markers in our pyproject.toml to help Poetry identify the right version to install. poetry install should now work for all supported Python version. I don't think there's any reason to explain this in the documentation since a contributor should not have to think about this. It's up to the maintainers to make sure the dependencies are properly specified.
Quite soon Python 3.9 will reach EOL and we can drop support entirely.