Pre-requisites
This document goes through the pre-requisites required for using eMach
and also guides users on setting up their systems to get
started.
Python
The first, and perhaps most obvious, requirement is for users to install Python on their systems. Version upwards of Python 3.8
are required for eMach
. Furthermore, it is highly recommended that users install Python via Anaconda
or Miniconda as the conda package manager is required in subsequent steps for
installing eMach
dependencies. In general, new users of Python are recommended to install Anaconda
as it comes with adittional
auxillary packages, the Spyder IDE (integrated development environment), Jupyter, and other features which make it very easy to get
started with Python out of the box. Users who are comfortable with Python, know exactly which IDE they want to use, and wish to
selectively install only the packages they require can go with the Miniconda
installation. This link succintly summarizes when
either installer should be used.
After installing Anaconda
/ Miniconda
, please ensure that paths to the Python and conda installations are included in the
Path
User Variables
(for Windows systems). This is required for your system to know how to run Python scripts, find relavent
Python packages, run conda
commands, etc. To verify this,
Search
environment variables
in the Windows search bar.Select
Edit the system environment variables
.Now click on the
Environment Variables...
button from theSystem Properties
window.Within
User Variables
, double click onPath
.A list of directories should now be visible, among which the directories where the newly install
python.exe
andconda.exe
files reside should be included. It will most likely be in the folderC:\Users\YourName\anaconda3
andC:\Users\YourName\anaconda3\Scripts
respectively.If the directories are not included, manually add them by clicking the
New
button and adding the above mentioned installation paths to thePath
User Variable
.
Warning
Be careful when modifying Environment Variables
. Inadvertent modifications can corrupt your system.
IDEs for Python
There are a large number of IDEs available out there for Python. Spyder, which comes along with the Anaconda
installation,
is most likely the path of least resistance for new users looking to quickly get started with Python. Spyder is however limited in
a lot of ways, its biggest disadvantage being the lack of flexibility to switch between different Python interpreters (versions)
and virtual environments. More information on Python virtual environments is provided below. Beginners will most likely not be
employing these features of Python anytime soon and therefore can continue with Spyder.
Other, more flexible IDEs for Python include Visual Studio Code and PyCharm. These IDEs have a lot of additional features, including syntax highlighting, auto-formatting, debugging capabilities, git integration, seamless transfer between virtual environments etc. However, there is a learning curve associated with these platforms.
Note
It is recommended that users switch to VS Code or PyCharm as soon as they are comfortable with Python as these IDEs enable much improved workflows.
Packages
The final step involved before one can begin using eMach
is to install the Python packages required by the module. Prior to
this stage, users should clone the eMach
git repository to their local system. A environment.yml
file has been provided at
the root directory of the repo. This file enables the re-creation of a Python conda environment which has been proven to work with
eMach
. Users are recommended to open this file and briefly glance through it to get an idea of the additional packages required
for eMach
, apart from what comes standard with Python.
There are 3 possible approaches users can follow to install the packages required by eMach
. Each of these approaches result in
a Python environment that is fully capable of working with each of eMach
’s different modules, however, each option does have
its own benefits / shortcomings.
Approach 1: Create a new eMach
Conda Environment
The primary purpose of the environment.yml
file is to automate the creation of new conda environments. Code developers can ensure
uniformity across systems by making use this feature as each developer will be working on the same Python virtual environment.
Beginners to Python are recommended to go through the Virtual Environments section before proceding with this
approach. Here, the procedure by which a new eMach
conda environment, having all the required dependecies and the right Python
version, can be created is provided.
Launch Windows
Command Prompt
.Navigate to the location of the
environment.yml
file or the root ofeMach
git repository withinCommand Prompt
.Run command
conda env create -f environment.yml
.Wait for the packages to install, enter
y
wherever required.Run
rectangle_example.py
fromexamples/mach_opt_examples
to confirm everything is in order.
Approach 2: Global Install of Select Packages
This approach is primarily recommended for users who want to install eMach
dependecies to their base Python install, but are
unable to do so with approach 3. Instead of updating the entire environment and trying to install all packages at once, each package
provided in the environment.yml
can be installed individually. The steps for doing so are:
Launch Windows
Command Prompt
Begin installing the
pygmo
package by runningconda install -c conda-forge pygmo=2.18.0
Try running the
rectangle_example.py
script fromexamples/mach_opt_examples
folderRun
conda install pkg_name==pkg_ver
on missing packages, if there are any
Approach 3: Global Install of All Packages
In this approach, the base Python installation is updated to include the packages required by eMach
.
Users can follow the steps provided below to install eMach
packages as per this approach.
Launch Windows
Command Prompt
.Navigate to the location of the
environment.yml
file or the root ofeMach
git repository withinCommand Prompt
.Run the following command :
conda env update --name base --file environment.yml --prune
.Wait for the packages to install, enter
y
if required.Run
rectangle_example.py
fromexamples/mach_opt_examples
to confirm everything is in order.
Warning
Anaconda
comes with a large Python base
. Updating such environments can take a very long time. If you are
running into this issue, consider following approach 1 or 2.
Congratulations! You have successfully completed all installations required to start using eMach
. You can now try running other
examples provided within the examples
folder to confirm everything is working as expected.
Note
Users following approach 1 should ensure the example scripts are being executed from the right Python environment.
More Information on Using Virtual Environments with Python (Approach 1)
This section has been added to help approach 1 users be more “Python savvy”. This section gives an overview of Python virtual environments and provides necessary links to enable users to work with virtual environments using VS code.
Virtual environments are isolated environments for Python projects. These environments become extremely useful when users start
dealing with multiple Python projects, each of which might have different, and at times, confilcting dependencies. For eg: if one
project requires numpy=0.13
whereas another requires numpy=1.22
, we would have to re-install the desired version of numpy
each time we switch between projects. Python overcomes this problem with virtual environments. By using different
environments for different projects, users can not only change the packages used, but can even change the very version of Python
employed between projects. This link provides a more detailed
explaination of Python virtual environments.
While virtual environments themselves are IDE agnostic, using IDEs such as Visual Studio Code or PyCharm makes it far easier to leverage their potential than using others such as Spyder. Tips and tricks for using VS Code with virtual environments:
Beginners should follow this video for an easy to understand, step-by-step guide of using VS Code with Python virtual environments.
To render any graphical elements, like graphs or charts, run in interactive window mode.
If you run into issues with running your scripts from a virtual environment even after following the above tutorial, try adding the following entries to the
settings.json
file.
{
"python.terminal.activateEnvironment": true,
"terminal.integrated.defaultProfile.windows": "Command Prompt"
}
Tip
When using virtual environments, it is always a good idea to confirm which paths your scripts are looking at to run Python
and access packages. This can be done by importing the sys
package and running print(sys.path)
. Make sure that all paths
agree with your expectations based on the location of your virtual environment.