Installation & Setup

EasyDynamics is a cross-platform Python library compatible with Python 3.11 through 3.12.

To install and set up EasyDynamics, we recommend using Pixi, a modern package manager for Windows, macOS, and Linux.

Main benefits of using Pixi

• Ease of use: Pixi simplifies the installation process, making it accessible even for users with limited experience in package management.
• Python version control: Pixi allows specifying and managing different Python versions for each project, ensuring compatibility.
• Isolated environments: Pixi creates isolated environments for each project, preventing conflicts between different package versions.
• PyPI and Conda support: Pixi can install packages from both PyPI and Conda repositories, providing access to a wide range of libraries.

An alternative installation method using the traditional pip package manager is also provided.

Installing with Pixi recommended

This section describes the simplest way to set up EasyDynamics using Pixi.

Installing Pixi

• Install Pixi by following the instructions on the official Pixi Installation Guide.

Setting up EasyDynamics with Pixi

• Initialize a new Pixi project and navigate into it:

  pixi init easydynamics
  cd easydynamics
  

• Set the Python version for the Pixi environment (e.g., 3.12):

  pixi add python=3.12
  

• Add the GNU Scientific Library (GSL) dependency:

  pixi add gsl
  

• Add EasyDynamics with the visualization extras, which include optional dependencies used for simplified visualization of charts and tables. This can be especially useful for running the Jupyter Notebook examples:

  pixi add --pypi "easydynamics[visualization]"
  

• Add a Pixi task to run EasyDynamics commands easily:

  pixi task add easydynamics "python -m easydynamics"
  

Updating Pixi and EasyDynamics

• To update all packages in the Pixi environment, including EasyDynamics:

  pixi update
  

• To update Pixi itself to the latest version:

  pixi self-update
  

Uninstalling Pixi

• Follow the official Pixi Guide.

Classical Installation

This section describes how to install EasyDynamics using the traditional method with pip. This approach is more flexible and suitable for users familiar with Python package management and virtual environments.

Warning

Currently, classical installation doesn't allow installing the GNU Scientific Library (GSL) dependency automatically. As a result, the calculation engine pdffit2 will not be available. To make it work, ensure that GSL is installed on your system.

Alternatively, consider using the Pixi installation method described in the Installing with Pixi section, which handles GSL installation automatically.

Environment Setup optional

We recommend using a virtual environment to isolate dependencies and avoid conflicts with system-wide packages. If any issues arise, you can simply delete and recreate the environment.

Creating and Activating a Virtual Environment:

• Create a new virtual environment:

  python3 -m venv venv
  

• Activate the environment:

  macOS Linux Windows

  . venv/bin/activate
  

  . venv/bin/activate
  

  . venv/Scripts/activate      # Windows with Unix-like shells
  .\venv\Scripts\activate.bat  # Windows with CMD
  .\venv\Scripts\activate.ps1  # Windows with PowerShell
  

• The terminal should now show (venv), indicating that the virtual environment is active.

Deactivating and Removing the Virtual Environment:

• Exit the environment:

  deactivate
  

• If this environment is no longer needed, delete it:

  macOS Linux Windows

  rm -rf venv
  

  rm -rf venv
  

  rmdir /s /q venv
  

Installing from PyPI

EasyDynamics is available on PyPI (Python Package Index) and can be installed using pip.

We recommend installing the latest release of EasyDynamics with the visualization extras, which include optional dependencies used for simplified visualization of charts and tables. This can be especially useful for running the Jupyter Notebook examples. To do so, use the following command:

pip install 'easydynamics[visualization]'

If only the core functionality is needed, the library can be installed simply with:

pip install easydynamics

To install a specific version of EasyDynamics, e.g., 1.0.3:

pip install 'easydynamics==1.0.3'

To upgrade to the latest version:

pip install --upgrade easydynamics

To upgrade to the latest version and force reinstallation of all dependencies (useful if files are corrupted):

pip install --upgrade --force-reinstall easydynamics

To check the installed version:

pip show easydynamics

Installing from GitHub alternative

Installing unreleased versions is generally not recommended but may be useful for testing.

To install EasyDynamics from the develop branch of GitHub, for example:

pip install git+https://github.com/easyscience/dynamics-lib@develop

To include extra dependencies (e.g., visualization):

pip install 'easydynamics[visualization] @ git+https://github.com/easyscience/dynamics-lib@develop'

How to Run Tutorials

EasyDynamics includes a collection of Jupyter Notebook examples that demonstrate key functionality. These tutorials serve as step-by-step guides to help users understand the data analysis workflow. They are available as static HTML pages in the Tutorials section.

In the next sections, we explain how to set up Jupyter and run the tutorials interactively in two different ways: locally or online via Google Colab.

If you decide to run the tutorials locally, you need to download them first. This can be done individually via the Download Notebook button available on each tutorial page, or all at once using the command line, as shown below.

Run Tutorials Locally with Pixi recommended

• Navigate to your existing Pixi project, created as described in the Installing with Pixi section.
• Add JupyterLab and the Pixi kernel for Jupyter:

  pixi add --pypi jupyterlab pixi-kernel
  

• Download all the EasyDynamics tutorials to the tutorials/ directory:

  pixi run easydynamics download-all-tutorials
  

• Start JupyterLab in the tutorials/ directory to access the notebooks:

  pixi run jupyter lab tutorials/
  

• Your web browser should open automatically. Click on one of the *.ipynb files and select the Python (Pixi) kernel to get started.

Classical Run Tutorials Locally

• Install Jupyter Notebook and IPython kernel:

  pip install notebook ipykernel
  

• Add the virtual environment as a Jupyter kernel:

  python -m ipykernel install --user --name=venv --display-name "EasyDynamics Python kernel"
  

• Download all the EasyDynamics tutorials to the tutorials/ directory:

  python -m easydynamics download-all-tutorials
  

• Launch the Jupyter Notebook server (opens browser automatically at http://localhost:8888/):

  jupyter notebook tutorials/
  

• Open one of the *.ipynb files and select the EasyDynamics Python kernel to get started.

Run Tutorials via Google Colab

Google Colab lets you run Jupyter Notebooks in the cloud without any local installation. This is the fastest way to start experimenting with EasyDynamics.

• Ensure you have a Google account.
• Go to the Tutorials section.
• Click the Open in Google Colab button on any tutorial.