docs: Convert best-practices.rst -> best-practices.md via rst2myst

Author: rht

docs/best-practices.md

@@ -0,0 +1,80 @@
+# Best Practices
+
+Here are some general principles that have proven helpful for developing models.
+
+## Model Layout
+
+A model should be contained in a folder named with lower-case letters and
+underscores, such as `thunder_cats`. Within that directory:
+
+- `README.md` describes the model, how to use it, and any other details.
+  Github will automatically show this file to anyone visiting the directory.
+- `model.py` should contain the model class.  If the file gets large, it may
+  make sense to move the complex bits into other files, but this is the first
+  place readers will look to figure out how the model works.
+- `server.py` should contain the visualization support, including the server
+  class.
+- `run.py` is a Python script that will run the model when invoked via
+  `mesa runserver`.
+
+After the number of files grows beyond a half-dozen, try to use sub-folders to
+organize them. For example, if the visualization uses image files, put those in
+an `images` directory.
+
+The [Schelling](https://github.com/projectmesa/mesa-examples/tree/main/examples/schelling) model is
+a good example of a small well-packaged model.
+
+It's easy to create a cookiecutter mesa model by running `mesa startproject`
+
+## Randomization
+
+If your model involves some random choice, you can use the built-in `random`
+property that Mesa `Model` and `Agent` objects have. This works exactly
+like the built-in `random` library.
+
+```python
+class AwesomeModel(Model):
+  # ...
+
+  def cool_method(self):
+    interesting_number = self.random.random()
+    print(interesting_number)
+
+class AwesomeAgent(Agent):
+  # ...
+  def __init__(self, unique_id, model, ...):
+    super().__init__(unique_id, model)
+    # ...
+
+  def my_method(self):
+    random_number = self.random.randint(0, 100)
+```
+
+(The agent's random property is just a reference to its parent model's
+`random` property).
+
+When a model object is created, its random property is automatically seeded
+with the current time. The seed determines the sequence of random numbers; if
+you instantiate a model with the same seed, you will get the same results.
+To allow you to set the seed, make sure your model has a `seed` argument in its
+constructor.
+
+```python
+class AwesomeModel(Model):
+
+  def __init__(self, seed=None):
+    pass
+
+  def cool_method(self):
+    interesting_number = self.random.random()
+    print(interesting_number)
+
+>>> model0 = AwesomeModel(seed=0)
+>>> model0._seed
+0
+>>> model0.cool_method()
+0.8444218515250481
+>>> model1 = AwesomeModel(seed=0)
+>>> model1.cool_method()
+0.8444218515250481
+```