Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Dev/0.3.2 #422

Merged
merged 31 commits into from
Apr 29, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
ea7fe20
Create SingleMetricOptimization class; add implementations for short …
jenni-niels Jul 28, 2021
1b25630
Add Gingleator child class of SingleMetricOptimizer for finding incre…
jenni-niels Jul 29, 2021
bdb2b01
Add more docs.
jenni-niels Jul 30, 2021
9707760
Merge branch 'main' into optimizations
jenni-niels Feb 23, 2022
282559a
Refactor SingleMetricOptimizer class to have generator function over …
jenni-niels Feb 23, 2022
49c3711
Add progressbar options to SingleMetricOptimizer class.
jenni-niels Feb 24, 2022
0043af4
add example notebook; patch progress bar
jenni-niels Feb 24, 2022
f414214
Add simulated annealing functionality
jenni-niels Feb 24, 2022
568b157
Update docs to bring inline with partition generator refactoring effort.
jenni-niels Feb 28, 2022
1cebba5
Delint
jenni-niels Feb 28, 2022
24260a2
minor typo fixes
gabeschoenbach Mar 1, 2022
0e17f4f
last few typo fixes
gabeschoenbach Mar 1, 2022
ec935fe
one more typo
gabeschoenbach Mar 1, 2022
665d0ae
increase plt size
gabeschoenbach Mar 1, 2022
3c2f40b
clear up class summary docs; "privatize" all instance variables and e…
jenni-niels Mar 1, 2022
e0b188f
Add minimizing compactness example to notebook and add markdown cells…
jenni-niels Mar 2, 2022
f1a233f
fix some typos and jumpcycle call
gabeschoenbach Mar 8, 2022
9e35545
Merge remote-tracking branch 'upstream/main' into optimizations
cdonnay Mar 29, 2024
f4725de
fix random module
cdonnay Apr 1, 2024
2fc3d1e
Merge pull request #361 from jenni-niels/optimizations
peterrrock2 Apr 12, 2024
b67ce87
Formatting, type hints, and making consistent doc strings
peterrrock2 Apr 12, 2024
3a6efc4
Double-checking that the example notebook runs and grabbing the json …
peterrrock2 Apr 12, 2024
5b90ed4
Fix the epsilon balance bug
peterrrock2 Apr 24, 2024
f0b2dc0
Update the way that the region aware works.
peterrrock2 Apr 25, 2024
12724a5
Add `from_random_assignment` method to the partition class
peterrrock2 Apr 25, 2024
30955ee
Update the optimizer docs
peterrrock2 Apr 25, 2024
a4366f9
All the doc updates
peterrrock2 Apr 26, 2024
08b981c
Add / fix tests for new features
peterrrock2 Apr 28, 2024
a833b5c
Fix some docs stuff
peterrrock2 Apr 28, 2024
2a30296
Fix for #417
peterrrock2 Apr 28, 2024
9fa629e
Fix Chris comments
peterrrock2 Apr 29, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ Installation
Supported Python Versions
-------------------------

The most recent version of GerryChain (as of February 2024) supports
The most recent version of GerryChain (as of April 2024) supports

- Python 3.9
- Python 3.10
Expand Down Expand Up @@ -196,7 +196,7 @@ adjacencies or reading in shapefiles, then run
This approach sometimes fails due to compatibility issues between our
different Python GIS dependencies, like ``geopandas``, ``pyproj``,
``fiona``, and ``shapely``. If you run into this issue, try installing
the dependencies using the `geo_settings.txt <https://github.com/mggg/GerryChain/raw/main/docs/geo_settings.txt>`_
the dependencies using the `geo_settings.txt <https://github.com/mggg/GerryChain/tree/main/docs/geo_settings.txt>`_
file. To do this, run ``pip install -r geo_settings.txt`` from the
command line.

Expand Down
1 change: 1 addition & 0 deletions docs/_static/BG_05.json

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ repository, where `bug reports and feature requests`_, as well as
user/updaters
user/data
user/geometries
user/optimizers

We also highly recommend the resources prepared by Daryl R. DeFord of
MGGG for the 2019 MIT IAP course `Computational Approaches for Political Redistricting`_.
Expand All @@ -73,6 +74,7 @@ MGGG for the 2019 MIT IAP course `Computational Approaches for Political Redistr
topics/reproducibility
topics/tools
topics/contributing
topics/reporting


.. toctree::
Expand Down
243 changes: 243 additions & 0 deletions docs/repeated_subsections/reproducible_envs.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,243 @@
Making an Environment Reproducible
----------------------------------

If you are working on a project wherein you would like to ensure
particular runs are reproducible, it is necessary to invoke

- **MacOS/Linux**: ``export PYTHONHASHSEED=0``
- **Windows**:

- PowerShell ``$env:PYTHONHASHSEED=0``
- Command Prompt ``set PYTHONHASHSEED=0``

before running your code. This will ensure that the hash seed is deterministic
which is important for the replication of spanning trees across your runs. If you
would prefer to not have to do this every time, then you need to modify the
activation script for the virtual environment. Again, this is different depending
on your operating system:

- **MacOS/Linux**: Open the file ``.venv/bin/activate`` located in your working
directory using your favorite text editor
and add the line ``export PYTHONHASHSEED=0`` after the ``export PATH`` command.
So you should see something like::

_OLD_VIRTUAL_PATH="$PATH"
PATH="$VIRTUAL_ENV/Scripts:$PATH"
export PATH

export PYTHONHASHSEED=0

Then, verify that the hash seed is set to 0 in your Python environment by
running ``python`` from the command line and typing
``import os; print(os.environ['PYTHONHASHSEED'])``.

- **Windows**: To be safe, you will need to modify 3 files within your virtual
environment:

- ``.venv\Scripts\activate``: Add the line ``export PYTHONHASHSEED=0`` after
the ``export PATH`` command. So you should see something like::

_OLD_VIRTUAL_PATH="$PATH"
PATH="$VIRTUAL_ENV/Scripts:$PATH"
export PATH

export PYTHONHASHSEED=0

- ``.venv\Scripts\activate.bat``: Add the line ``set PYTHONHASHSEED=0`` to the
end of the file. So you should see something like::

if defined _OLD_VIRTUAL_PATH set PATH=%_OLD_VIRTUAL_PATH%
if not defined _OLD_VIRTUAL_PATH set _OLD_VIRTUAL_PATH=%PATH%

set PATH=%VIRTUAL_ENV%\Scripts;%PATH%
rem set VIRTUAL_ENV_PROMPT=(.venv)
set PYTHONHASHSEED=0

- ``.venv\Scripts\Activate.ps1``: Add the line ``$env:PYTHONHASHSEED=0`` to the
end of the before the signature block. So you should see something like::

# Add the venv to the PATH
Copy-Item -Path Env:PATH -Destination Env:_OLD_VIRTUAL_PATH
$Env:PATH = "$VenvExecDir$([System.IO.Path]::PathSeparator)$Env:PATH"

$env:PYTHONHASHSEED=0

# SIG # Begin signature block

After you have made these changes, verify that the hash seed is set to 0 in your
Python environment by running ``python`` from the command line and typing
``import os; print(os.environ['PYTHONHASHSEED'])`` in the Python prompt.

Reproducible Environments in VSCode and Jupyter Lab
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In general, it is easier to use jupyter notebooks with bespoke virtual environments
through a text editor like `VSCode <https://code.visualstudio.com/download>`_, but
we will also show how to do this using the standard Jupyter Lab interface as well.

Regardless of which method you prefer, you will need to make sure that you have
installed the ``ipykernel`` package into the virtual environment that you will be
working with:

.. code:: console

pip install ipykernel


VSCode
~~~~~~

First you will want to make sure that you have
`installed VSCode <https://code.visualstudio.com/download>`_.
Then, you can click on "File" in the upper-left and select "Open Folder" to open the
folder with your project and virtual environment in it. This should look something like
this:

.. image:: ../user/images/vscode_tutorial/open_the_folder.png
:align: center

Notice that I have the folder ``.venv`` in my file explorer. This is just my virtual
environment that I created for this project.


To install the Python extension, open the extensions view by clicking on the square
icon on the left side of the window. Then, search for "Python" and install the
extension that is published by Microsoft. This will allow you to use the Python
interpreter in your virtual environment and will give you some helpful things like
code completion and debugging in the event that you would like it.

.. image:: ../user/images/vscode_tutorial/python_extension_vscode.png
:align: center

Likewise, we will want to install the "Jupyter" extension:

.. image:: ../user/images/vscode_tutorial/jupyter_extension_vscode.png
:align: center

Now let's make a new jupyter notebook. You can do this by right-clicking in the file
explorer (or by using the File menu) and selecting "New File".

.. image:: ../user/images/vscode_tutorial/Make_a_new_file.png
:align: center

.. raw:: html

&nbsp;

Then, you will want to save the file with the extension ``.ipynb`` since we are making
a jupyter notebook. We can now open the file and select the Python interpreter
that we would like to use:


.. image:: ../user/images/vscode_tutorial/select_kernel_vscode.png
:align: center

.. image:: ../user/images/vscode_tutorial/select_python_env.png
:align: center

.. image:: ../user/images/vscode_tutorial/selecting_correct_venv.png
:align: center

And now we are done! We can now use all of the packages in our ``.venv`` virtual environment
inside of our jupyter notebook:

.. image:: ../user/images/vscode_tutorial/show_gerrychain_import.png
:align: center

Of course, if you would like to, you may also use a different name for your virtual environment,
or you can even use the same process to allow for multiple virtual environments in the same
project!


Jupyter Lab / Notebook
~~~~~~~~~~~~~~~~~~~~~~

In order to use Jupyter Lab or Jupyter Notebook, we will need to make sure that it is installed
for our virtual environment. This can be done by running the following command:

.. code:: console

pip install jupyter

Then, we will want to install the kernel for our virtual environment. This can be done by running
the following command:

.. code:: console

python -m ipykernel install --user --name=.venv


Now, we can open Jupyter Lab by running the following command:

.. code:: console

jupyter lab

You will now see that the ``.venv`` is available in your list of kernels:

.. image:: ../user/images/jupyter_tutorial/jupyter_lab.png
:align: center


.. warning::

As opposed to VSCode, Jupyter Lab does not automatically use the virtual environment that
you have in your project, so you will need to make sure that you have the correct kernel
installed before opening the lab. You can see which kernel you are using by looking at the
output of the following command:

.. code:: console

jupyter kernelspec list

this will output something like

.. code:: console

Available kernels:
.venv /Users/username/.local/share/jupyter/kernels/.venv
python3 /usr/local/share/jupyter/kernels/python3

You will then need to inspect the output of this command to see where the kernel is located.
In the above example, we can see that the kernel ``.venv`` is located at
``/Users/username/.local/share/jupyter/kernels/.venv`` which is the correct location for the
current working project. However, if we were to make a new project in
``/Users/username/Desktop/another_project`` and make a new virtual environment in this
location with the same name of ``.venv``, then, after running the command
``python -m ipykernel install --user --name=.venv``,
the kernel will still look like it is located at
``/Users/username/.local/share/jupyter/kernels/.venv``, BUT this new kernel is actually
the one for for the second project and not the original! This is important to note because
if you are working on multiple projects and you have the same kernel name for each project,
things can get a little confusing, so it is best to always reinstall the appropriate kernel
before opening the project in Jupyter.

Of course, an easy fix for this is to just use a different name for the kernel in each project.
For example, I might make my kernel name for the project in
``/Users/username/Desktop/gerrychain_docs``
``venv_gerrychain_docs`` via the command

.. code:: console

python -m ipykernel install --user --name=venv_gerrychain_docs

and the kernel name for the project in
``/Users/username/Desktop/another_project`` ``venv_another_project``.


We can now make a new notebook and select the kernel that we would like to use:

.. image:: ../user/images/jupyter_tutorial/make_new_file.png
:align: center

.. image:: ../user/images/jupyter_tutorial/select_kernel.png
:align: center

.. raw:: html

&nbsp;

Lastly, we can import GerryChain and use it in our notebook:

.. image:: ../user/images/jupyter_tutorial/show_import_working.png
:align: center
12 changes: 12 additions & 0 deletions docs/topics/reporting.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
================
Reporting Issues
================

Sometimes, you may encounter a problem with GerryChain, and that is okay! We would
love to hear about it so that we can fix it. If you can provide a minimal example that
reproduces the issue, please feel free to report it on the `GitHub issue tracker
<https://github.com/mggg/GerryChain/issues>`_.

In the event that you would prefer not to post the issue publicly, you can also email
us at "code[at]mggg[dot]org". We will do our best to respond to your issue in a timely
manner. Thank you for your help in making GerryChain better!
Loading
Loading