DOC+BUG: Confusing sampling example and RuntimeError on Windows in usage_overview.rst

[hridaiiiEx]

Issue with current documentation:

Description

While following the usage_overview.rst documentation, I encountered two issues:

1. The sampling example is confusing and differs from the official tutorial.
2. The code raises a RuntimeError on Windows systems.
3. There are broken Links in Documentation.

---

Problem 1: Confusing Sampling Example

In the documentation, the sampling is written as:

idata = pm.sample(1000, tune=2000, cores=2)

However, in the top recommended Youtube tutorial by Chris Fonnesbeck titled "Getting Started with PyMC" Youtube it is stated that sampling is mostly automatic and can be done simply with: pm.sample() without any arguments. This discrepancy can confuse beginners.

Problem 2: RuntimeError on Windows

Running the given example raises:

RuntimeError: 
An attempt has been made to start a new process before the current process has finished its bootstrapping phase

Problem 3: Broken Links in Documentation

The "See also" section contains links such as:

• Tutorials
• Examples

However, clicking on these leads to a 404 error:
docs/source/learn/nb_tutorials/index.html
This suggests that the links are either outdated or incorrectly referenced.

---

Overall this section seems to be very confusing for beginners on a windows system.

Idea or request for content:

Summary

I prepared an alternative, clearer example for the usage_overview.rst page (same model as in the official tutorial). This PR will add the example as a separate folder rather than editing the existing file. I chose a new folder so the example can ship as:

• a runnable .py example file,
• a About_model.md (with plain text explanation),
• images for equations/figures (so equations render the same across viewers),
• and separate test/run instructions.

I used the guidance from Chris Fonnesbeck’s video (https://www.youtube.com/watch?v=jrU0UBr2z3k&t=1770s) which shows pm.sample() can be used with automatic defaults. I also encountered a Windows RuntimeError from multiprocessing and noticed several broken links in the docs (screenshots attached).

---

Problems found

1. Sampling example mismatch / clarity

   • The docs use explicit arguments (e.g. pm.sample(1000, tune=2000, cores=2)), while the tutorial suggests sampling is mostly automatic (pm.sample()).
   • This confuses beginners — suggestion: show the simple default example and show that it runs correctly.

2. RuntimeError on Windows

   • Running the example raises:

     RuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase
     

   • Likely caused by using multiprocessing (e.g. cores>1) without protecting the sample call or without guidance for Windows users.
   • Suggested fixes: either wrap example usage in if __name__ == "__main__":, set cores=1 in docs for Windows, or add a short note about Windows multiprocessing.

3. Broken links

   • Several “See also” links point to docs/source/learn/nb_tutorials/index.html and return 404. (Screenshot attached.)
   • Suggestion: update/remove links or point to correct pages.

---

Why a separate folder?

I created a separate folder because it lets me include:

• a clean, runnable .py example (so users can copy-paste and run without editing rst code blocks),
• about_model.md that explains how to run it,
• high-quality images for equations (so they look consistent),
• and additional plotting examples (I plan to add more az plots later).

If you prefer not to add a parallel folder, I can convert this to modifications of the existing .rst instead — please advise which you prefer.

---

What I can do next

• I can open a Draft PR with the folder (incomplete links are noted in the PR) so maintainers can review structure first.
• I can alternatively modify the existing usage_overview.rst if you prefer minimal changes.
• I can include a Windows note and update examples to avoid the RuntimeError.
• I can add more az plots in follow-up PRs.

---

Request

Please advise:

1. Do you prefer an in-place edit of usage_overview.rst or adding the separate folder as an alternative example?
2. If a new folder is acceptable, should I:
   • keep both (original + alternative), or
   • replace the existing example with the clearer version?

I plan to open a Draft PR

with a proposed structure for review. (and will mark it “Closes #<issue_number>” once the maintainers ask me to). Thanks!

[welcome]

]
🎉 Welcome to PyMC! 🎉 We're really excited to have your input into the project! 💖

If you haven't done so already, please make sure you check out our Contributing Guidelines and Code of Conduct.

[fonnesbeck]

On issue 1, the idea there (i.e. in my talk) is that you can just run sample with no arguments and get reasonable default values. It does not necessarily mean that you should. Also, part of the job of the docs is to illustrate the role of the important arguments to the function, so I'd be inclined to leave things as they are.

[fonnesbeck]

On issue 2, Windows performance is certainly a blind spot for us because none of the core developers (to my knowledge -- maybe @michaelosthege ?) use Windows, which makes testing difficult. If you have suggestions that may help Windows users we would welcome them!

On the face of it, an in-place edit should be sufficient, adding whatever pearls of wisdom you may have. We like to keep the core examples pretty simple, and the more complex or nuanced content moved over to pymc-examples.

[hridaiiiEx]

Thank you so much for your valuable insights. I will certainly keep this in mind and try to open another PR in order to add a few things in the existing files that makes the code runnable in windows as well. I hope I can contribute valuably to PyMC further on and continue to get your guidance.

I would really appreciate if you can also check my draft PR request #8127 and give me your thoughts.

Thank You!

On issue 2, Windows performance is certainly a blind spot for us because none of the core developers (to my knowledge -- maybe @michaelosthege ?) use Windows, which makes testing difficult. If you have suggestions that may help Windows users we would welcome them!

On the face of it, an in-place edit should be sufficient, adding whatever pearls of wisdom you may have. We like to keep the core examples pretty simple, and the more complex or nuanced content moved over to pymc-examples.

[michaelosthege]

Using PyMC on Windows works absolutely fine with zero changes to the code.

The RuntimeError you encountered suggests that your installation is broken.
Please follow the install instructions for conda: https://www.pymc.io/projects/docs/en/latest/installation.html

[hridaiiiEx]

Using PyMC on Windows works absolutely fine with zero changes to the code.

The RuntimeError you encountered suggests that your installation is broken. Please follow the install instructions for conda: https://www.pymc.io/projects/docs/en/latest/installation.html

I am extremely sorry for the inconvenience caused. I will make the required changes asap.

[openagentsworld-admin]

Hi PyMC team — issue #8126 documents reproducible doc-link 404s in docs/source/learn/nb_tutorials/index.html and a Windows multiprocessing RuntimeError in usage_overview.rst, with exact reproduction steps.

If it helps, OpenAgents World lets you open a scoped fix task with Review Instructions and a price you set; a freelancer can take it through the AI Worker role, and OpenAgents Review checks the delivery against your instructions before completion — short video: https://openagentsworld.com.

Happy to leave it here if it's not a fit.