Ce dépôt GitHub propose une collection de notebooks Jupyter conçus pour intégrer la programmation en Python dans l'enseignement de la chimie physique. Ces notebooks fournissent des exemples commentés et illustrés, couvrant des sujets tels que les dérivées et les intégrales, l'atome d'hydrogène et les représentations moléculaires. Ce dépôt inclut également des ressources pour des applications d'apprentissage automatique en chimie, comme les réseaux de neurones artificiels et les autoencodeurs. Pour utiliser ces outils, les utilisateurs sont invités à installer Jupyter ainsi qu'une distribution Python, Anaconda étant recommandée. Des instructions détaillées pour cloner le dépôt et exécuter les notebooks sont disponibles dans ce fichier README.md

🇬🇧 This GitHub repository offers a collection of Jupyter Notebooks designed to integrate Python programming into physical chemistry education. These notebooks provide commented and illustrated examples, covering topics such as derivatives and integrals, the hydrogen atom, and molecular representations. The repository also includes resources for machine learning applications in chemistry, like artificial neural networks and autoencoders. To utilize these materials, users are advised to install Jupyter and a Python distribution, with Anaconda being a recommended option. Detailed instructions for cloning the repository and running the notebooks are provided in the present README.md document

Table des Matières

• Document principal et pré-requis
• Installation et activation d'une distribution python
  • Introduction
  • Installation de miniconda
  • Activation d'un environnement conda
  • Installation des bibliothèques Python et des outils additionnels nécessaire
• Clonage du dépôt (repository) pyPhysChem et installation des bibliothèques Python nécessaires
• Utiliser ces notebooks à l'aide de JupyterLab
• Liste des changements
• Comment citer ce travail ?

🇬🇧 Table of Contents

• Main document and prerequisites
• Installation and activation of a Python distribution
  • Introduction
  • Installing miniconda
  • Activation of a conda environment
  • Installation of the required Python libraries and additional tools
• Cloning of the pyPhysChem repository and installation of the required libraries
• 🇬🇧 Use these notebooks with JupyterLab
• LList of changes
• How to cite this work?

Document principal et pré-requis / 🇬🇧 Main document and prerequisites

Il faut lire le fichier TOC.ipynb, qui renvoie vers des sous-thèmes. Chaque sous-thème est introduit par les objectifs de ces TP, ainsi qu'une table des matières qui permet d'accéder aux cours/TP et aux exercices.

Pré-requis : des notions très élémentaires d'algorithmique (variables, tests conditionnels, boucles). 🤔 Vous voulez rafraîchir vos connaissances et renforcer vos acquis ? Le notebook PPCL.ipynb est fait pour ça. Il est un peu long, mais il en vaut la peine 😊. Vous pouvez peut-être même vous lancer sans aucune connaissance algorithmique de base. C'est à vous de voir si cela vous suffit.💪💪🏼💪🏿

🇬🇧 Read the TOC.ipynb file, which points to subtopics. Each subtopic is introduced by the goals of the course, as well as a table of contents that allows access to the courses/tutorials and exercises.

🇬🇧 Prerequisite : very basic notions of algorithmic (variables, conditional tests, loops). 🤔 Do you want to refresh your knowledge and reinforce your skills? This is what the PPCL.ipynb notebook is for. It's a bit long, but it's worth the effort 😊. You may even be able to get started without any basic algorithmic knowledge. It's up to you to see if that's enough for you.💪💪🏼💪🏿

Installation et activation d'une distribution Python / 🇬🇧 Installation and activation of a Python distribution

Introduction

Il faut d'abord avoir installé Jupyter ainsi qu'une distribution python sur son PC.

La solution la plus simple est d'installer et utiliser Anaconda, qui est une distribution libre et open source du langage de programmation Python :

• Les versions de paquetages sont gérées par le système de gestion de paquets conda
• Elle comprend également Anaconda Navigator, qui est une interface graphique "user-friendly"
• Les applications suivantes sont disponibles par défaut dans le navigateur :
  • JupyterLab & Jupyter Notebook
  • Spyder
  • RStudio
  • ...
• Anaconda est disponible pour MacOS, Windows, Linux.
• Il existe une version "light", nommée miniconda

On va ensuite apprendre à installer miniconda, ce qui va imposer de lancer des lignes de commandes

🇬🇧 First install Jupyter as well as a Python distribution on your PC.

🇬🇧 A simple and easy possibility is to install Anaconda, a free and opensource distribution of the Python programming language:

• Package versions are managed by the package management system conda
• It also includes a user friendly GUI, Anaconda Navigator
• The following applications are available by default in Navigator:
  • JupyterLab & Jupyter Notebook
  • Spyder
  • RStudio
  • ...
• Anaconda runs under MacOS, Windows, Linux
• There is a lighter version, called miniconda

🇬🇧 We're next going to learn how to install miniconda, which will require us to run command lines

Installation de miniconda / 🇬🇧 Installing miniconda

• téléchargez le programme d'installation pour votre OS (Windows/macOS/linux)

• exécutez-le :

  • Windows : allez dans le répertoire Téléchargement, cliquez deux fois sur l'icone Miniconda3-latest-Linux-x86_64.exe
  • Linux : ouvez un terminal, cd vers le répertoire Téléchargement, tapez bash Miniconda3-latest-Linux-x86_64.sh

• pendant l'installation :

  • validez l'accord de licence

  • choisissez le répertoire d'installation - ou sinon validez la proposition de répertoire par défaut

    • Windows: C:\Users\<premières-lettres-de-votre-username>\miniconda3
    • Linux : /home/<votre-username>/miniconda3)

  • finalisez l'installation :

    • Windows : selectionnez les Options Avancées de Configuration. Ne cochez pas "Ajoutez Miniconda3 à la variable d'environnement PATH" si vous craignez un conflit avec une autre distribution Python que vous pourriez avoir dans votre compte local
    
    • Linux: vous devez répondre à une question concernant la variable d'environnement PYTHONPATH. Répondez "non" si vous craignez un conflit avec une autre distribution Python que vous pourriez avoir dans votre compte local
    

• 🇬🇧 download the installer for your OS (Windows/macOS/linux)

• 🇬🇧 execute it:

  • Windows: go to the download directory, double click on the Miniconda3-latest-Linux-x86_64.exe icon
  • Linux: open a terminal, cd to the download directory, type bash Miniconda3-latest-Linux-x86_64.sh

• 🇬🇧 during the installation process:

  • validate the license agreement

  • choose the installation folder - or accept the folder defined by default:

    • Windows: C:\Users\<first-letters-of-your-username>\miniconda3
    • Linux : /home/<your-username>/miniconda3)

  • finalize the installation

    • Windows: select the Advanced Configuration Options. Do not select the "Add Miniconda3 to my PATH environment variable" checkbox if you fear a conflict with another python distribution that would you have in your local account.
    
    • Linux: you need to answer a question about the PYTHONPATH environment variable. Answer no if you fear a conflict with another python distribution that would you have in your local account.
    

🇬🇧 Whatever the OS of your computer is, you end up with a "base" python distribution, provided and manageable with conda. Given the PATH environment selection chosen during the installation, you might have to activate the python environment

Activation d'un environnement conda / 🇬🇧 activation of a conda environment

Windows

• cherchez l'application Anaconda Powershell Prompt dans le champ de recherche:
  🇬🇧 search for the Anaconda Powershell Prompt application in the search field:
• exécutez-là. Vous devriez voir apparaître un terminal, avec une invite de commande (prompt) (base) PS C:\Users\<first-letters-of-your-username>>
  🇬🇧 execute it. You should see a terminal, with a (base) PS C:\Users\<first-letters-of-your-username>> prompt:
  

Linux

• ouvez un terminal
  🇬🇧 open a terminal

• tapez la commande:
  🇬🇧 type the command:

  eval "$(/home/<your-username>/miniconda3/bin/conda shell.bash hook)"

  L'invite de commande (prompt) devrait débuter avec (base):
  🇬🇧 The prompt should now start with (base):

  

• pour désactiver l'environnement de "base" de conda, tapez:
  🇬🇧 to deactivate the "base" python environment of conda, type:

  conda deactivate

Installation des bibliothèques Python et des outils additionnels nécessaires / 🇬🇧 Installation of the required Python libraries and additional tools

Introduction

Vous devez installer dans votre environnement Python des bibliothèques additionnelles ainsi qu'un outil, nommé git. git est utilisé pour gérer et suivre les modifications du code ou des fichiers d'un projet, permettant le contrôle de version, la collaboration et une gestion efficace des projets en développement logiciel. Une option très utile est fournie par la commande git clone, qui permet de créer une copie locale d'un dépôt Git distant, comme celui hébergé sur GitHub. Cette commande télécharge l'intégralité du projet, y compris son historique, ses branches et ses fichiers, vous permettant de travailler localement sur le code. Il faut aussi installer les outils Jupyter, qui ne font pas partie de la distribution miniconda.

🇬🇧 You must install additional libraries in your Python environment, as well as a tool named git. git is used to manage and track changes in code or project files, enabling version control, collaboration, and efficient project management in software development. A very useful option is provided by the git clone command, used to create a local copy of a remote Git repository, such as one hosted on GitHub. This command downloads the entire project, including its history, branches, and files, allowing you to work on the code locally. You also need to install the Jupyter tools, which are not included in the miniconda distribution.

Installation de git et des outils Jupyter / 🇬🇧 Installation of git and of the Jupyter tools

• Sous Windows, ouvrez l'application Anaconda PowerShell Prompt.
  🇬🇧 On Windows, open an Anaconda PowerShell Prompt

• Sous Linux, ouvez un terminal et activez conda:
  🇬🇧 On Linux, open a terminal and activate conda:

  eval "$(/home/<your-username>/miniconda3/bin/conda shell.bash hook)"

• tapez la commande ci-dessous:
  🇬🇧 type the command below:

  conda install git jupyter

  
  L'affichage devrait être simlaire à la capture d'écran ci-dessous:
  🇬🇧 You should see something similar to:

  

Installation de bibliothèques Python additionnelles / 🇬🇧 Installation of additional Python libraries

Cela doit être fait avec des lignes de commande, à l'aide Anaconda PowerShell Prompt (Windows) ou dans un terminal où conda a été activé (Linux). Vous pouvez utiliser :

conda install <name-of-the-python-library>

ou

pip install <name-of-the-python-library>

conda install est un gestionnaire de paquets qui gère des dépendances complexes et des bibliothèques non-Python. Cela le rend idéal pour les environnements scientifiques et de data science. Il dispose d'une résolution de dépendances robuste et est utilisé pour créer des environnements indépendants avec des versions spécifiques de paquets et de Python lui-même. En revanche, pip install est spécifique aux paquets Python provenant de PyPI. Il est plus rapide pour les installations simples, mais ne gère pas aussi bien les dépendances non-Python. Utilisez conda pour des configurations complexes avec des bibliothèques externes, et pip pour des projets Python plus simples.

En résumé, conda est précieux pour les projets de data science nécessitant des dépendances complexes ou une compatibilité entre plusieurs langages de programmation, tandis que pip reste un excellent choix pour des flux de travail plus simples basés uniquement sur Python.

Dans la section suivante, il sera recommandé d'installer les bibliothèques Python utilisées par pyPhysChem avec pip

🇬🇧 It must be done with lines of command, in an Anaconda PowerShell Prompt (Windows) or in a terminal where conda has been activated (Linux). You can either use:

conda install <name-of-the-python-library>

or

pip install <name-of-the-python-library>

🇬🇧 conda install is a package manager that handles complex dependencies and non-Python libraries. That makes it ideal for scientific and data science environments. It has robust dependency resolution and is used to create isolated environments with specific versions of packages and Python itself. In contrast, pip install is specific to Python packages from PyPI. It is faster for simple installations, but doesn’t handle non-Python dependencies as well. Use conda for complex setups with external libraries, and pip for straightforward Python projects.

🇬🇧 In short, conda is valuable for data science projects that require complex dependencies or cross-language compatibility, while pip remains a great choice for more straightforward Python-based workflows.

🇬🇧 In the next section, it will be recommended to install the Python libraries used by pyPhysChem with pip

🔝 top 🔝

Clonage du dépôt (repository) pyPhysChem et installation des bibliothèques Python nécessaires / 🇬🇧 Cloning of the pyPhysChem repository and installation of the required libraries

Clonage / 🇬🇧 Cloning

C'est la méthode recommandée, car elle facilite la mise à jour des notebooks. Vous devez saisir des lignes de commandes depuis l'application Anaconda PowerShell Prompt (Windows) ou bien depuis un terminal où conda a été activé (Linux)
🇬🇧 This is the recommended way, given the ease of updating notebooks. You need to enter command lines from the Anaconda PowerShell Prompt application (Windows) or from a terminal where conda has been activated (Linux).

Depuis le répertoire où vous voulez installer les notebooks, tapez la commande :
🇬🇧 Go into the folder in which the notebooks will be installed, and type:

git clone https://github.com/rpoteau/pyPhysChem.git

Vous avez maintenant un répertoire pyPhysChem dans le répertoire depuis lequel vous avez lancé la commande git
🇬🇧 You now have a pyPhysChem folder installed in the folder from which the git command was ran

Mise à jour / 🇬🇧 Update

pyPhysChem étant un projet en évolution, il faut régulièrement vérifier qu'il n'y a pas de mise à jour. La commande suivante met si nécessaire à jour le contenu du répertoire pyPhysChem
🇬🇧 pyPhysChem being a work-in-progress project, it is necessary to regularly check for a possible update. The content of the pyPhysChem folder is updated by using the following process:

• allez d'abord dans le répertoire pyPhysChem
  first go into the pyPhysChem folder

• puis tapez
  and then enter:

  git pull origin main

Installation des bibliothèques requises / 🇬🇧 Installation of the necessary libraries

Comme pour les autres installations, toutes les commandes s'exécutent à partir d'un terminal Linux avec l'environnement de base activé, ou bien depuis l'application Anaconda PowerShell Prompt sous Windows

🇬🇧 As with other installations, all commands are run from a Linux terminal with the base environment activated, or from the Anaconda PowerShell Prompt application on Windows

• allez d'abord dans le répertoire pyPhysChem
  🇬🇧 first go into the pyPhysChem folder

• il y a un fichier nommé requirements4pyPhysChem-LastVersion.txt, qui contient la liste de toutes les bibliothèques nécessaires pour exécuter tous les codes Python des notebooks Jupyter de pyPhysChem
  Exécutez la commande ci-dessous, puis soyez patient(e)s
  🇬🇧 There is a file named requirements4pyPhysChem-LastVersion.txt, which contains the list of all the libraries required to run all the Python codes from the Jupyter notebooks of pyPhysChem
  Run the command below, then be patient:

  pip install -r requirements4pyPhysChem-LastVersion.txt

• Dépannage: si une erreur d'installation se produit car une bibliothèque est indisponible pour votre OS, éditez le fichier requirements4pyPhysChem-LastVersion.txt, effacez la ligne correspondante, et relancez la commande d'installation
  🇬🇧Troubleshooting: If an installation error occurs because a library is unavailable for your OS, edit the requirements4pyPhysChem-LastVersion.txt file, delete the corresponding line, and rerun the installation command

• il ne vous reste plus qu'à vérifier qu'il n'y a pas de problèmes. La commande pip check doit renvoyer No broken requirements found
  🇬🇧All that’s left is to check that there are no issues. The command pip check should return No broken requirements found

🔝 top 🔝

Utiliser ces notebooks à l'aide de JupyterLab / 🇬🇧 Use these notebooks with JupyterLab

• Ouvrez un terminal (Linux - et n'oubliez pas d'activer conda avec eval "$(/home/<your-username>/miniconda3/bin/conda shell.bash hook)") ou bien l'application Anaconda PowerShell Prompt (Windows)
  🇬🇧Open a terminal (Linux - and don't forget to activate conda with eval "$(/home/<your-username>/miniconda3/bin/conda shell.bash hook)") or the Anaconda PowerShell Prompt application (Windows)

• Allez dans le répertoire qui contient pyPhysChem (commande cd <chemin_d_accès>)
  🇬🇧Navigate to the folder that contains pyPhysChem (cd <pathway> command)

• tapez la commande :
  🇬🇧 enter the command:

  jupyter-lab TOC.ipynb

• jupyter-lab devrait s'ouvrir dans votre navigateur:
  🇬🇧 Jupyter-lab should open in your browser:

  

🔝 top 🔝

Liste des changements / 🇬🇧 List of changes

🔄 Liste des changements / List of changes 🔄

Comment citer ce travail ? / 🇬🇧 How to cite this work?

Si vous utilisez des parties significatives des codes publiés dans ce dépôt github, ou bien s'il a été utile pour votre auto-formation, veuillez le citer comme suit :

🇬🇧 If you use pieces of code of this github repository that turned out to be decisive to your work, or that have been useful for your self-learning, please cite it as follows:

N. Bernard, M. Charnay, S. Christodoulou, I. C. Gerber*, F. Jolibois* and R. Poteau*, Python in the Physical Chemistry lab (pyPhysChem) github repository, release v. 2.0.5 (2024), doi: 10.5281/zenodo.14050542

🔝 top 🔝