remove how-to guide and update docs in places

[quaquel]

The How-To guide was outdated with virtually nothing being relevant for MESA 3. I have gone ahead and completely removed it for now. I have updated to tutorial to remove the references to it (which themselves already seemed a bit out of place).

[EwoutH]

Let's see: Replacing schedulers is covered in the migration guide, Random you're the expert on, the only thing I'm unsure about it batch_run. Is that outdated? I do remember the issue, was it ever fixed?

Git history shows it was added here:

• Default batch_run to 1 CPU #1300

And solved this issue:

• batch_run should default to running on 1 CPU #1210

With some discussion here:

• Should batch_run default to running on 1 CPU? #1202

[quaquel]

the only thing I'm unsure about it batch_run. Is that outdated? I do remember the issue, was it ever fixed?

It's the only thing that is not clearly outdated. The underlying thing is, however, not a mesa-specific thing but is all about the proper use of Python's multiprocessing.

However, (1) the provided code is not correct nor up to date. freeze_support should not be needed. (2) The use of if __name__ == '__main__': is recommended on all operating systems. In fact, without it, the code will fail on MacOS and Windows because both don't use os.fork but os.spawn to instantiate new worker processes. (3) you can easily do multiprocessing in jupyter lab, even on Windows as long as the model is imported into the notebook rather than defined in the notebook. Again this has to do with understanding how multiprocessing creates the worker processes.

In my view, this information, if we want to keep it, should be shifted to the module-level docstring of batch-run.

[EwoutH]

Sounds good, let’s write up the gist of it there.

[quaquel]

Sounds good, let’s write up the gist of it there.

Ok,I'll just at the update to that docstring to this PR later today.