Tag: technews

Design, modelling, and simulation of real-world AI systems to improve performance on object detection tasks using finite state machines.

Background

Problem understanding

Recently, I came across one of the great cases of using Raspberry Pi and Python for creating a computer vision-based system for object detection. In short, one guy created a device that keeps the neighbor’s chickens away from his property. After following the Reddit thread, it became apparent that the problem is quite pervasive and not limited to certain bird species, if at all. The top rated comments include:

“I need one of these for the ducks my neighbor feeds and then they sh*t all over my lawn.” — Light_Beard

“I need this for cats in my yard at night.” — Buddha_

“Does it work on kids on Halloween? Asking for a friend.” — HardPawns

Well, one might argue that the problem is not that important and quite legitimately suggest simply asking the neighbors to sort out those hens. However, this is clearly not an engineer’s way to tackle this. Suppose you had already built an AI-assisted bird detection system equipped with a water blaster to chase unwelcome hens away from the yard. The caveat is that its operating version does not perform as well as expected, resulting in still noticeable water usage for sprinkling and lawn cleanup. Hence, chickens run and water bills remain lofty. How to address the challenge?

Model-based engineering for complex systems

Here, we are about to tackle this real-world problem by designing a computational model to simulate the complete chicken-on-the-lawn cycle and later optimize its parameters so that we can reduce water consumption. To do so, we will employ different techniques, including those from automata theory and randomized algorithms.

In particular, this article focuses on modelling and simulation aspects so that you learn how to describe behavior of a real system and design a finite state machine reflecting its dynamics. Then, you will explore the path of implementing such systems in Python and discover ways to leverage computer vision-based models by optimizing its performance on object detection. This should be fun!

Disclaimer: This work is a part of the “Bird by Bird using Deep Learning” series and is devoted to modelling and simulation of real-life systems for computer vision applications using finite automata. All actors, states, events and outputs are the products of the FSM design process for educational purposes only. Any resemblance to actual persons, birds, or real events is purely coincidental.

Introducing the related work

Finite state machines for modelling and simulation

Finite-state machine (FSM) or finite automaton is a mathematical model that can be used to represent and analyse dynamic behavior of a system by describing it through discrete states, transitions between those states, and a set of rules triggering these transitions.

The history of FSM traces back to the mid-20th century, marked by pivotal milestones in automata theory and the theory of computation. Early contributions by luminaries such as Alan Turing and John von Neumann laid the foundation, but it was in the 1950s and 1960s that FSM took a significant leap forward. Notably, Edward F. Moore and George H. Mealy independently introduced two primary types of FSMs, Moore and Mealy machines, respectively.

These FSM types differ in their approach: Moore machines determine next states based solely on the current state, while the Mealy ones associate outputs with the current state and input, offering enhanced adaptability. Originally used in digital circuits, FSMs, in particular Mealy machines, with their responsiveness to external input signals, have become widespread in the design of complex systems that accompany our daily lives.

FSMs are found in both hardware and software applications. Look around — almost all electronic and computing devices have some sort of finite automata — from vending machines to CPUs, from basic electronic devices to programmable logical controllers for smart home automation. They are also taken in software and game development and, of course, can be used to create adaptive AI-assisted systems for real-time object detection.

Discrete math strikes back

At its core, a deterministic finite automaton includes states, inputs, and a transition function. States represent distinct conditions of the system, while inputs trigger switches between states. The transition function defines rules of how the machine transitions between states. Mathematically, such state machine can be represented using a 5-tuple, denoted as M=(Q, Σ, δ, q₀, F), where:

• Q is a set of states representing distinct configurations of the system.
• Σ is a set of inputs consisting of events that trigger state changes.
• Transition function δ governs how the system switches between states given an input (δ:Q×Σ→Q).
• Initial State q₀ is a starting state of the system to be initialized with, where q₀∈Q.
• F is a subset of Q (F⊆Q) consisting of final states.

This way, for any given state and specific input symbol, there is a unique next state determined by the transition function δ, which is typically represented by a state transition table or diagram, specifying transitions given a combination of the current state and inputs.

FSM design process

The design process of an FSM involves identifying the states (and inputs if applicable), defining the transition function, as well as specifying the initial and final states. The following methodology can be employed for translating complex systems into comprehensible models, aiding in the further analysis, design, and implementation phases. A 5-step FSM design process includes:

1. Understanding the problem, analyse the structure of the system.
2. Defining key components for a conceptual model to be designed.
3. Creating a state diagram or defining a state-transition table.
4. Implementing the machine’s states, inputs and outputs, transition logic.
5. Testing and experimentally validating the FSM.

This iterative process allows to design a concise representation of the real system’s behavior, allowing for approximations and refinements along the process. For instance, after implementing an FSM (Step 4), you may want to further verify and update the specifications (Steps 2–3), same applies to moving from the experimentation (Step 5) back to the problem definition (Step 1), in order to create a working model that is sufficiently detailed and useful to solve a particular problem.

State machine example

Let us take a simple case of the chicken-on-the-lawn scenario, where a bird can either be present on the lawn or not, as a function of external stimuli initiated by the engineer, who, in turn, can either rest or chase away unwelcome guests trespassing on his property. Thus, the controlling object (the engineer) is intended to compensate for the uncertainty of the independent actors (chickens) parameters. In the given example, the set of final states F includes only one state in which the system terminates, say at the end of the day when there are no chickens around. In this way:

• Q = {q₀, q₁, q₂, ⊙}: Set of states representing No-/Chicken.
• Σ = {α₀, α₁, α₂}: Set of input events — Engineer Rest/Chase, and Sunset.
• F = {⊙} contains the final state representing the end of the day.

Figure 1 provides a state transition diagram consisting of nodes (states) connected by edges (next-state transitions), with the labels above the arcs specifying input events triggering the transitions.

This representation captures the binary nature of the problem, in which a chicken can either be present or not on the lawn. The system responds to the events triggered by the engineer or the sunset. In the diagram, the initial and final states are indicated by circles. The transition function δ for this FSM can also be written in a tabular form, showing state transitions and control actions for the system, as shown in Table 1.

Table 1. State-transition table for the chicken-on-the-lawn FSM example

+========================+========================+========================+
| Current State          | Input Event            | Next State             |
+========================+========================+========================+
| q₀ ≡ ”No Bird”         | α₀ ≡ ”Engineer Rest”   | q₁                     |
+------------------------+------------------------+------------------------+
| q₁ ≡ ”Bird Present”    | α₁ ≡ ”Engineer Chase”  | q₀                     |
+------------------------+------------------------+------------------------+
| q₀                     | α₂ ≡ ”Sunset”          | ⊙                     |
+------------------------+------------------------+------------------------+

Thus, by completing five straightforward steps we designed a simple state machine. Now that everything has been explained, let’s finally create an FSM-based model representing our challenge with birds on the lawn.

On dealing with the birds-on-the-lawn challenge

What they do on the lawn

As you have learnt in the previous section, finite automata can be used to model almost any process. Imagine you have some chickens hopping around in your backyard this afternoon. What are they doing? Just observe. They’re always moving, singing, or interacting. They’re often flying, probing, or eating. On some occasions, they’re displaying, or doing something that draws our attention, like those neighbor’s chickens messing up with the grass, but let’s set those particulars aside for now. Well, eventually, all the birds are s***ing (nothing personal, feathery ones). For the FSM design, we won’t get into the finer details, instead distilling essential components with logic for our simulation. Let the FSM take water adventures to the next level of play!

System description

Concerning the chickens, here, we are going to describe the system to reflect our down-to-earth scenario in order to optimize parameters of the object detection system and reduce water costs for lawn cleaning. For the reference, take another look at the previous FSM example. This simple machine differs from the real-life system in some particular aspects. First, we want to actualize the controlling object to include an AI-based device aimed at detecting and repelling birds, this time by means of a high-pressure water sprinkler gun (so the engineer can “self-loop” into the rest state).

Second, we will need to update and/or extend the set of possible states, events, and transitions reflecting complexity of the updated system’s setup. For the latter, why don’t we consider additional bird categories that can be recognized by a computer vision model (e.g., turkeys) thus being potential independent actors for our FSM. Moreover, assuming that bird size varies across species, an irrigation control system would need a more intense water flow and/or pressure to successfully chase a bulky turkey off the lawn than it would for a chicken. Hereafter, for brevity’s sake, we will refer to the chicken-and-turkey-on-the-lawn problem as the CaT problem.

Conceptual modelling

In order to model scenarios where the object detection system has to monitor, classify, and interact with objects trespassing on the property, we will define states, events, and transitions that represent the different aspects of this situation. Our goal is to capture the various states the object detection system and chickens can be in, as well as the events that trigger state transitions.

For the logic design scenarios, consider that at any given moment a bird can enter the yard, mess up with the lawn (or not), and leave the property either for its own or if it was successfully detected and chased away by the AI-based lawn security system. Now, let’s define some main components of the FSM simulation.

States represent possible conditions reflecting the CaT scenarios:

• For hopping targets: Spawn and Intrusion statuses, Attacking and its result, Leaving the lawn.
• For the AI system: Detection State, Sprinkling State.
• Initial state “Start” relates to the entry point of the simulation.
• Final state “End” denotes the termination point of the simulation.

Transitions govern how the system switches between states based on inputs. For instance, the AI model may overlook a bird and miss the sprinkling process, thus, resulting in a number of consequences for the lawn. Here are some other scenarios and conditions we can anticipate:

• From “Intrusion” to “Target Detected” on the “Detection” event.
• From “Target Detected” to “Bird Leaves” events through the sequence of “Sprinkling” and “Hit” events after an intruded bird has been detected and hit by the water sprinkler successfully.
• From “Bird Present” to “Attack”, in case the system has failed at target detection and prediction steps, while the bird was actually on the lawn. The same event shall take place under the conditions that the bird-intruder was detected, but the shot was missed by the system.

This way, the FSM will dynamically progress from one state to another as the AI system interacts with the chickens hopping around. To make task easier and less error-prone, we create a combined state transition and conditions table:

Table 2. FSM inputs describing the events triggering state changes

+====+==================================+==================+================+
| ID | Input Description                | Defence System   | Enemy Tactics  |
|    |                                  | Operation Mode   | and Waypoints  |
+====+==================================+==================+================+
| X₁ | Bird is present on the lawn      |                  | Hopping        |
+----+----------------------------------+ Object detection +----------------+
| X₂ | Bird intrudes the lawn           |                  | Start hopping  |
+----+----------------------------------+------------------+----------------+
| X₃ | AI-powered detector spots a bird | Start sprinkling | Hopping (still)|
+----+----------------------------------+------------------+----------------+
| X₄ | Bird is hit successfully¹        |                  |                |
+----+----------------------------------+        -         | Intimidation   |
| X₅ | Target is susceptible²           |                  |                |
+----+----------------------------------+------------------+----------------+
| X₆ | Bird spoiled the lawn            |                  | Hopping merrily|
+----+----------------------------------+ Object detection +----------------+
| X₇ | Bird leaves the lawn             |                  | Retreat        |
+----+----------------------------------+------------------+----------------+
| X₈ | Simulation period ends (sunset)  |        -         | -              |
+----+----------------------------------+------------------+----------------+
ID - input identifier
¹ - aiming and sprinkling modules operated correctly
² - water flow rate is strong enough to chase the bird away

State transition tables

Now, after identifying states and events, we’ll write a combined state transition table with Boolean expressions for the next states. In table 3, we see how the inputs described in Table 2 steer the transitions between the simulation states.

Table 3. FSM state transition table with next-stage transition logic

+========================+========================+========================+
| Current State          | Transition Formula     | Next State             |
+========================+========================+========================+
| Start                  | TRUE                   | Spawn                  |
+------------------------+------------------------+------------------------+
|                        | X₁ ∨ X₂                | Intrusion              |
|                        |------------------------+------------------------+
| Spawn                  | ¬X₁ ∧ ¬X₂              | Empty lawn             |
+                        |------------------------+------------------------+
|                        | X₈                     | End                    |
+------------------------+------------------------+------------------------+
|                        | X₃                     | Target detected        |
| Intrusion              |------------------------+------------------------+
|                        | ¬X₃                    | Not detected           |
+------------------------+------------------------+------------------------+
|                        | X₃                     | Target detected        |
| Empty lawn             |------------------------+------------------------+
|                        | ¬X₃                    | Not detected           |
+------------------------+------------------------+------------------------+
| Target detected        | TRUE                   | Sprinkling             |
+------------------------+------------------------+------------------------+
|                        | X₁                     | Attacking              |
| Not detected           |------------------------+------------------------+
|                        | ¬X₁                    | Not attacked           |
+------------------------+------------------------+------------------------+
|                        | ¬X₁ ∨ ¬X₄ ∨ ¬X         | Miss                   |
| Sprinkling             |------------------------+------------------------+
|                        | X₁ ∧ X₄ ∧ X₅           | Hit                    |
+------------------------+------------------------+------------------------+
|                        | ¬X₁                    | Spawn                  |
| Miss                   |------------------------+------------------------+
|                        | X₁                     | Attacking              |
+------------------------+------------------------+------------------------+
| Hit                    | TRUE                   | Bird leaves            |
+------------------------+------------------------+------------------------+
|                        | ¬X₆                    | Not attacked           |
| Attacking              |------------------------+------------------------+
|                        | X₆                     | Bird attacked          |
+------------------------+------------------------+------------------------+
|                        | ¬X₇                    | Spawn                  |
| Not attacked           |------------------------+------------------------+
|                        | X₇                     | Bird leaves            |
+------------------------+------------------------+------------------------+
|                        | ¬X₇                    | Spawn                  |
| Bird attacked          |------------------------+------------------------+
|                        | X₇                     | Bird leaves            |
+------------------------+------------------------+------------------------+
| Bird leaves            | TRUE                   | Spawn                  |
+------------------------+------------------------+------------------------+

In most cases, a single input determines the next state. However, we have to consider a number of conditions simultaneously for switching from “Spawn” or “Sprinkling”. You could also notice that for some states, transitions don’t depend on the external information, like for “Start” or “Hit”. These states are either special (as “Start”) or trigger auxiliary actions. The latter don’t have a direct influence on the story we simulate (i.e. in that regard, they can be combined with the subsequent states) but are important for gathering simulation statistics.

Finally, let’s look at its visual representation. Figure 3 presents the state transition graph corresponding to the CaT system going through during its lifetime. You can probably see the connection already. Moving forward with the following article, you will learn how to implement this FSM in Python and how to use it to optimize parameters of the AI-assisted bird detection system in order to reduce water cost.

Conclusions

In this article, we explored how to apply finite state machines in practice to build a model for addressing the CaT problem, allowing for high-level problem analysis and solution design.

We have described complex yard processes by applying the FSM formalism to individual actors and the interactions between them, thereby creating a holistic view of the internal dynamics of the real-world situation, in which we had to deal with neighborhood birds trespassing on the property.

This allowed us to create a simulation that reflects, among other things, the operation of the AI-assisted security system equipped with a water pressure controller for sprinkling and aimed at object detection and chasing away unwelcome guests spoiling the lawn.

What’s next?

In the upcoming series of articles, we will further investigate the topic of simulation of real-life scenarios using FSMs and its practical applications for addressing a non-analytic optimization problem of water cost reduction.

Specifically, the next article will feature a Python tutorial from which you will learn how to implement an FSM-driven simulation from scratch as well as how to employ it as a part of a stochastic optimization pipeline. Based on the simulation created, we then examine how to leverage it for improving the resource efficiency of our lawn security system by applying Monte-Carlo and eXplainable AI (XAI) techniques to optimize performance of a computer vision-based subsystem for bird detection.

Interested to keep it on? Stay updated on more materials at — https://github.com/slipnitskaya/caltech-birds-advanced-classification and https://medium.com/@slipnitskaya.

References

1. Moore, Edward F. “Gedanken-experiments on sequential machines.” Automata studies 34 (1956): 129–153.
2. Mealy, George H. “A method for synthesizing sequential circuits.” The Bell System Technical Journal 34.5 (1955): 1045–1079.
3. Sipser, M. “Introduction to the Theory of Computation.” 2nd ed., Thomson Course Technology (2006).

Finite Automata Simulation for Leveraging AI-Assisted Systems was originally published in Towards Data Science on Medium, where people are continuing the conversation by highlighting and responding to this story.

Setting A Dockerized Python Environment — The Hard Way

This post will review different methods to run a dockerized Python environment from the command line (CLI). Am I recommending you run your Python environment from the CLI? Absolutely not!

There are better ways to set up a Python development environment, such as using VScode and the Dev Containers extension. We will use the “hard way” to set up a Python environment from the CLI for learning purposes. We will review different approaches to launching a container with the run command and see how to customize a built-in image using the Dockerfile.

Prerequisites

To follow along with this tutorial, you will need the following:

• Docker Desktop (or equivalent) if you are using a macOS or Windows OS machine, or Docker installed if you are using a Linux OS
• Docker Hub account to pull the image from.

Throughout this tutorial, we will use the official Python image — python:3.1o.

Getting Started

Let’s get started by pulling the official Python 3.10 image from Docker Hub. First, let’s log in to Docker Hub by using the docker logincommand:

docker login docker.io                                                                                                                                                                      ok
Authenticating with existing credentials...
Login Succeeded

Next, we will use the docker pull command from the terminal:

docker pull python:3.10                                                                                                                                                                     ok

If this is the first time you pull the image, you should expect the following output:

3.10: Pulling from library/python
66932e2b787d: Pull complete
4afa7e263db1: Pull complete
c812910e5e62: Pull complete
f4e4299bb649: Pull complete
5213cc2f9120: Pull complete
4a3b5b2f0e66: Pull complete
c214ceb1cabf: Pull complete
f5336038b15c: Pull complete
Digest: sha256:f94601bb6374b0b63835a70c9e5c3ba1b19bc009133900a9473229a406018e46
Status: Downloaded newer image for python:3.10
docker.io/library/python:3.10

You can review the image details with the use of the docker images command:

docker images                                                                                                                                                                          ok  11s
REPOSITORY   TAG       IMAGE ID       CREATED      SIZE
python       3.10      f7537c504c9a   7 days ago   1.01GB

Before running the container, let’s review the image metadata with the docker inspect command:

docker inspect python:3.10

This will return the below JSON output:

[
    {
        "Id": "sha256:f7537c504c9a91a22c9a255ee02048e7079cacdee583290e8238c605d17f9600",
        "RepoTags": [
            "python:3.10"
        ],
        "RepoDigests": [
            "python@sha256:f94601bb6374b0b63835a70c9e5c3ba1b19bc009133900a9473229a406018e46"
        ],
        "Parent": "",
        "Comment": "buildkit.dockerfile.v0",
        "Created": "2024-02-03T10:49:13Z",
        "Container": "",
        "ContainerConfig": {
            "Hostname": "",
            "Domainname": "",
            "User": "",
            "AttachStdin": false,
            "AttachStdout": false,
            "AttachStderr": false,
            "Tty": false,
            "OpenStdin": false,
            "StdinOnce": false,
            "Env": null,
            "Cmd": null,
            "Image": "",
            "Volumes": null,
            "WorkingDir": "",
            "Entrypoint": null,
            "OnBuild": null,
            "Labels": null
        },
        "DockerVersion": "",
        "Author": "",
        "Config": {
            "Hostname": "",
            "Domainname": "",
            "User": "",
            "AttachStdin": false,
            "AttachStdout": false,
            "AttachStderr": false,
            "Tty": false,
            "OpenStdin": false,
            "StdinOnce": false,
            "Env": [
                "PATH=/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                "LANG=C.UTF-8",
                "GPG_KEY=A035C8C19219BA821ECEA86B64E628F8D684696D",
                "PYTHON_VERSION=3.10.13",
                "PYTHON_PIP_VERSION=23.0.1",
                "PYTHON_SETUPTOOLS_VERSION=65.5.1",
                "PYTHON_GET_PIP_URL=https://github.com/pypa/get-pip/raw/dbf0c85f76fb6e1ab42aa672ffca6f0a675d9ee4/public/get-pip.py",
                "PYTHON_GET_PIP_SHA256=dfe9fd5c28dc98b5ac17979a953ea550cec37ae1b47a5116007395bfacff2ab9"
            ],
            "Cmd": [
                "python3"
            ],
            "ArgsEscaped": true,
            "Image": "",
            "Volumes": null,
            "WorkingDir": "",
            "Entrypoint": null,
            "OnBuild": null,
            "Labels": null
        },
        "Architecture": "arm64",
        "Variant": "v8",
        "Os": "linux",
        "Size": 1005570383,
        "VirtualSize": 1005570383,
        "GraphDriver": {
            "Data": {
                "LowerDir": "/var/lib/docker/overlay2/d2fd76e7396796018a959209b51fe8311a188c8eae8e339e9e556de0889ca0bd/diff:/var/lib/docker/overlay2/bbedb25c5aa6ec3f2fc632e62a53989a329b907143fac165f899209293627a69/diff:/var/lib/docker/overlay2/ed6a4bf49214e6b496b7716443b8de380481cd9416bc4a378f29183c9129786f/diff:/var/lib/docker/overlay2/ac9543f44a835c203fb0b0b28958d94df72d206c9060c9d83307b39f50355102/diff:/var/lib/docker/overlay2/94a9f92c36ea6251feda52be8e76ec4da4a9c66b744a29472e1ccfdf34a6f69d/diff:/var/lib/docker/overlay2/6ee22c274256834a64008022856d365d91373bb490ae9f2f1723cb524b246a29/diff:/var/lib/docker/overlay2/2fa272376e0ce68f4f34f18e5ecb1ddd58a32fb20a82e5a417514047f8e684a3/diff",
                "MergedDir": "/var/lib/docker/overlay2/f2d64d1affbe99afb05251435f7705cb97e2efa4f8febb494b4cbaa21e7f742a/merged",
                "UpperDir": "/var/lib/docker/overlay2/f2d64d1affbe99afb05251435f7705cb97e2efa4f8febb494b4cbaa21e7f742a/diff",
                "WorkDir": "/var/lib/docker/overlay2/f2d64d1affbe99afb05251435f7705cb97e2efa4f8febb494b4cbaa21e7f742a/work"
            },
            "Name": "overlay2"
        },
        "RootFS": {
            "Type": "layers",
            "Layers": [
                "sha256:9f8c60461a42fd9f275c56f4ec8fea8a8ea2d938493e316e830994a3814cf0aa",
                "sha256:927a28cdbf6c1705342b2cba0069457313815058dcebe1996e46cade38a09370",
                "sha256:e85139d96aee18e99fc964d02546be48cc6a4d4dfd9f465a91f172b7c535e55f",
                "sha256:f3168ba6a8d2ec30e12002ad5b7b497cf7409f3e19cc8d8f447f6cf4231a2482",
                "sha256:acbc6c8127209b09fa336e354037fdc630d3594e15174f2bc1bdbf31d5591376",
                "sha256:06c4da96c7dd2fbbbb541e000bd0ea4cfbf7c80b24f098a9d67f677ef5e6c63e",
                "sha256:1cdf208dc10679cf5db6d4f0e17ff6d5bfe754b4195ddd3b153b6d1ff51ce909",
                "sha256:5d6f554f67c7da9d34763916bac632a450902c6e6fdbf9244f888f110fd37740"
            ]
        },
        "Metadata": {
            "LastTagTime": "0001-01-01T00:00:00Z"
        }
    }
]

The ispect command provides a lot of useful information about the image, such as the layers information, the image size, the hardware architecture, etc. As we want to run the image, the most interesting detail is the CMD setting. The CMDcommand in the Dockerfile defines what command to execute during the container launch time. We can parse from the above output the CMD information with the jq package:

docker inspect python:3.10 | jq '.[] | .Config | .Cmd'                                                                                                                                      ok
[
  "python3"
]

As you can see, the image is set to execute the python3 command during the container run time. Let’s now launch the container using the run command:

docker run python:3.10

And… nothing happens. The reason for that, in short, is that we need to give Docker access to the terminal. We will use the interactive and TTY arguments to run the image in an interactive mode:

docker run --interactive --tty python:3.10

This will attach the terminal to the container and open Python inside the container:

While we were able to launch Python inside a container, it is not as useful:

• We cannot create, edit, and run scripts inside the Python interpreter
• By default, the Python image comes with a limited number of libraries. In this mode, you cannot add additional ones
• Last but not least, the container is ephemeral. Once you stop it, all the work is lost

For example, if we will try to load pandas, we will get the following error:

In the following sections, we will address those issues by creating a Dockerfile and customizing the base image functionality. This includes adding the following features:

• Set a virtual environment and install packages with a requirements file. For simplicity,
• Install a vim editor to edit files
• Change the CMD command to open a shell terminal upon launch (as opposed to the Python interpreter). This will enable us to create new scripts, edit, and execute from the terminal

Customize the Base Image

To customize the Python environment and make the above changes, we will create a Dockerfile with the following functionality:

• Import the Python image — python:3.10
• Set a virtual environment
• Install required libraries
• Install vim editor
• Expose a bash terminal

Setting a Python Virtual Environment

To set up a Python virtual environment, we will use the following two helper files:

requirements.txt

wheel==0.40.0
pandas==2.0.3

This file defines the list of Python libraries to install in the virtual environment. For example, in this case, we will install the Pandas library, version 2.0.3. Generally, I also install the wheels library, which handles C dependencies.

The next helper file is the below bash script, which sets the virtual environment and installs the required libraries from the requirements.txt file.

set_python_env.sh

#!/usr/bin/env bash

PYTHON_ENV=$1

python3 -m venv /opt/$PYTHON_ENV  
        && export PATH=/opt/$PYTHON_ENV/bin:$PATH 
        && echo "source /opt/$PYTHON_ENV/bin/activate" >> ~/.bashrc

source /opt/$PYTHON_ENV/bin/activate

pip3 install -r ./requirements/requirements.txt

Note: We use a variable (marked as $1) to define the environment name, which will be assigned to the PYTHON_ENV variable. Using variables during the build is a good practice, as it enables us to modify some of the image characteristics without modifying the code. We will assign the variable via the Dockerfile.

Let’s explain the following concatenate code from the above bash script that sets the virtual environment:

python3 -m venv /opt/$PYTHON_ENV  
    && export PATH=/opt/$PYTHON_ENV/bin:$PATH 
    && echo "source /opt/$PYTHON_ENV/bin/activate" >> ~/.bashrc

The above three lines of code include three concatenate expressions:

• First, the python3 -m venv /opt/$PYTHON_ENV set a virtual environment with the venv command
• Second, add the virtual environment path to the PATH variable
• Third, add to the .bashrc file the activate command of the environment. This will ensure that whenever we launch the terminal, it will activate this virtual environment by default (otherwise, you will have to do it manually upon the launch of the environment)

Once the environment is set, we use the source command to activate the environment, and the pip3 command to install the libraries inside the environment.

Creating a Dockerfile

After we review the helper files, let’s see how they are incorporated inside the below Dockerfile.

Dockerfile

FROM python:3.10

ARG PYTHON_ENV=my_env
ENV PYTHON_ENV=$PYTHON_ENV

RUN mkdir requirements

COPY requirements.txt set_python_env.sh /requirements/

RUN bash ./requirements/set_python_env.sh $PYTHON_ENV

RUN apt-get update && 
    apt-get install -y 
    vim 
    && apt update


CMD ["/bin/sh", "-c", "bash"]

As you can see, we are using the same image — python:3.10as our base image.

Next, we set an argument named PYTHON_ENV with the ARG command to define the virtual environment name. We setmy_env as the default value, which can be modified during the build time using the arg argument. We use the PYTHON_ENV argument to set an environment variable as well.

Before setting the virtual environment, we will create inside the image a new library under the root folder named requirements and use the COPY command to copy the above helper files — requirements.txt and set_my_python.sh to the requirements folder.

Next, we call the bash script — set_my_python.sh , which sets the virtual environment and installs the required libraries. As mentioned above, we use the PYTHON_ENV variable as an argument with the set_my_python.sh file to set the virtual environment name dynamically.

We use the apt command to install vim — a CLI editor. This will enable us to edit code on via the container CLI.

Last but not least, use the CMD command to launch a shell terminal using bash:

CMD ["/bin/sh", "-c", "bash"]

At this point, we have the below files in the local folder:

.
├── Dockerfile
├── requirements.txt
└── set_python_env.sh

Let’s now go ahead and build the image with the docker build command:

docker build .-f Dockerfile -t my_python_env:3.10
[+] Building 47.3s (10/10) FINISHED
 => [internal] load build definition from Dockerfile                                                 0.2s
 => => transferring dockerfile: 389B                                                                 0.0s
 => [internal] load .dockerignore                                                                    0.2s
 => => transferring context: 2B                                                                      0.0s
 => [internal] load metadata for docker.io/library/python:3.10                                       0.0s
 => [1/5] FROM docker.io/library/python:3.10                                                         1.3s
 => [internal] load build context                                                                    0.4s
 => => transferring context: 460B                                                                    0.0s
 => [2/5] RUN mkdir requirements                                                                     0.5s
 => [3/5] COPY requirements.txt set_python_env.sh /requirements/                                     0.2s
 => [4/5] RUN bash ./requirements/set_python_env.sh my_env                                          26.8s
 => [5/5] RUN apt-get update &&     apt-get install -y     vim     && apt update                    17.4s
 => exporting to image                                                                               0.7s
 => => exporting layers                                                                              0.6s
 => => writing image sha256:391879baceea6154c191692d4bcb9ec9690de6dc4d5edd5b2ed13f6c579dd05c         0.0s
 => => naming to docker.io/library/my_python_env:3.10

Let’s run again the docker images command to review the current images:

docker images                                                  
REPOSITORY      TAG       IMAGE ID       CREATED         SIZE
my_python_env   3.10      391879baceea   7 minutes ago   1.23GB
python          3.10      f7537c504c9a   8 days ago      1.01GB

As you can note, adding the virtual environment and installing the packages added about 250 Mb to the image size.

Running the Python Environment

After we built the image, let’s launch the image with the docker run command and check if the above properties are defined as expected:

docker run --interactive --tty my_python_env:3.10

This launches the image in interactive mode, and opens a bash terminal as expected:

As you can notice in the above screenshot, it launched the container inside the bash terminal, and the virtual environment is set as expected as my_env. The pandas library was installed and can be loaded, and we can now edit files from the terminal.

One issue to take care of is that the container is still ephemeral. Therefore, any code we create inside the image is not exportable and will be lost after we stop the container from running.

A simple solution is to mount a volume with the volume argument. For simplicity, we will go ahead and mount the local folder, where we keep the Dockerfile and the helper files, to a new folder inside the container named my_scripts:

docker run -v .:/my_scripts  --interactive --tty my_python_env:3.10

And here is the output:

Once the folder is mounted, any file that is created, modified, or deleted from the mounted folder inside the container will be reflected to the local folder. This enables you to maintain your code when stopping the container.

Summary

In this tutorial, we reviewed how to set a dockerized Python environment using the command line. While this is neither a practical nor recommended approach to develop with Python, it is a great learning experience of Docker core commands and basic functionalities. We show how we can easily take a built-in image and customize it according to our needs. Last but not least, we saw how to mount a local folder to the container with the volume argument to transfer the container from an ephemeral mode to a persistent mode.

Resources

• A full tutorial for setting up a Dockerized Python environment with VScode and the Dev Containers — https://github.com/RamiKrispin/vscode-python
• Setting a dockerized Python development environment with GitHub template — https://medium.com/@rami.krispin/setting-a-dockerized-python-development-environment-template-de2400c4812b
• Docker vs. virtual environment — https://medium.com/@rami.krispin/running-python-r-with-docker-vs-virtual-environment-4a62ed36900f
• Dockerfile reference — https://docs.docker.com/engine/reference/builder/

Setting A Dockerized Python Environment — The Hard Way was originally published in Towards Data Science on Medium, where people are continuing the conversation by highlighting and responding to this story.