# pylimer-tools > # pylimer-tools > > [![Run Tests](https://github.com/GenieTim/pylimer-tools/actions/workflows/run-tests.yml/badge.svg)](https://github.com/GenieTim/pylimer-tools/actions/workflows/run-tests.yml) > [![Test Coverage (Python)](https://github.com/GenieTim/pylimer-tools/blob/main/.github/coverage.svg?raw=true)](https://github.com/GenieTim/pylimer-tools/actions/workflows/run-tests.yml) > [![Test Coverage (C++)](https://github.com/GenieTim/pylimer-tools/blob/main/.github/cpp-coverage.svg?raw=true)](https://github.com/GenieTim/pylimer-tools/actions/workflows/run-tests.yml) > [![Total Coverage](https://codecov.io/gh/GenieTim/pylimer-tools/branch/main/graph/badge.svg?token=5ZE1VSDXJQ)](https://codecov.io/gh/GenieTim/pylimer-tools) > [![Docs](https://github.com/GenieTim/pylimer-tools/actions/workflows/publish-documentation-html.yml/badge.svg)](https://github.com/GenieTim/pylimer-tools/actions/workflows/publish-documentation-html.yml) > [![PyPI version](https://badge.fury.io/py/pylimer-tools.svg)](https://pypi.org/project/pylimer-tools/) > [![Downloads](https://img.shields.io/pypi/dm/pylimer-tools.svg)](https://pypi.org/project/pylimer-tools/) > [![License](https://img.shields.io/pypi/l/pylimer-tools.svg)](LICENSE) > [![DOI](https://zenodo.org/badge/413754467.svg)](https://doi.org/10.5281/zenodo.17582030) > > Pronunciation: "pylimer” like "pü-limer”, with the "py” as in the German word "müde” (IPA: /ˈpyːlɪmɚ/). > > `pylimer-tools` is a toolkit for simulation, analysis, and data handling of bead–spring polymer systems in Python and C++. It combines high-level Python utilities with performant C++ extensions for common tasks in computational polymer science. > > ## Table of Contents > > - [pylimer-tools](#pylimer-tools) > - [Table of Contents](#table-of-contents) > - [1. Features](#1-features) > - [2. Installation](#2-installation) > - [Requirements](#requirements) > - [Stable Release](#stable-release) > - [Build from Source](#build-from-source) > - [Requirements](#requirements-1) > - [Build](#build) > - [3. Test Installation](#3-test-installation) > - [4. CLI Tools](#4-cli-tools) > - [5. Documentation](#5-documentation) > - [6. Development \& Testing](#6-development--testing) > - [Adding Features](#adding-features) > - [7. Citing](#7-citing) > - [8. Contributing](#8-contributing) > - [9. Code of Conduct](#9-code-of-conduct) > - [10. Acknowledgements](#10-acknowledgements) > - [11. License](#11-license) > - [Pronunciation Note](#pronunciation-note) > > ## 1. Features > > A selection of features includes: > > - Monte Carlo structure (network "universe”) generation > - Dissipative Particle Dynamics (DPD) simulation with slip-springs > - Maximum Entropy Homogenization Procedure (MEHP) with and without slip-links > - LAMMPS output readers: data, dump, thermodynamic outputs > - Network analysis: loops, chain reconstruction, degree statistics > - Structural metrics: radius of gyration, end-to-end distance, distributions > - Normal mode analysis for stress autocorrelation, loss and storage modulus > - Command line interfaces for batch workflows > > ## 2. Installation > > ### Requirements > > Python >= 3.9. > > ### Stable Release > > Stable release from PyPI: > > ``` > pip install pylimer-tools > ``` > > ### Build from Source > > #### Requirements > > Build requires CMake, a C++17 compiler, and (optionally) Ninja for faster builds. > > Additionally, the system packages `flex` and `bison` are required (`winflexbison` on Windows using `choco`) to build the dependency `igraph`. > > #### Build > > To build from source (compiles C++ extension): > > ``` > git clone https://github.com/GenieTim/pylimer-tools.git > cd pylimer-tools > pip install -e . > ``` > > Optional: Use provided helper scripts in `./bin` (e.g. `./bin/build-wheel.sh`, `./bin/build-tests.sh`). > > ## 3. Test Installation > > ```python > import pylimer_tools > import pylimer_tools_cpp > > print("Installed version: {} == {}".format( > pylimer_tools.__version__, > pylimer_tools_cpp.__version__ > )) > > ``` > > More examples: see the [examples in the documentation](https://genietim.github.io/pylimer-tools/auto_examples/index.html) and [their code in `examples/`](examples/). > Additionally, the [tests](tests/) and the [CLI Tools](src/pylimer_tools/) may serve as examples. > > ## 4. CLI Tools > > Installed console scripts: > > - `pylimer-generate-network` – generate random bead-spring networks using our MC generation procedure > - `pylimer-analyse-networks` – batch analysis / statistics given LAMMPS data (structure) files > - `pylimer-basic-lammps-stats` – quick structural stats from LAMMPS data (structure) file > - `pylimer-displace-randomly` – random displacement utility > > Run any with `--help` for usage. > > ## 5. Documentation > > Full documentation (API reference, tutorials, examples): > [https://genietim.github.io/pylimer-tools](https://genietim.github.io/pylimer-tools) > > ## 6. Development & Testing > > Clone and install in editable mode (see Installation). Then: > > ``` > ./bin/run-tests.sh # full test suite (Python + C++), includes benchmarks & tests that may fail > ./bin/run-tests-short.sh # quicker subset, generates coverage, is what's run in the CI > ./bin/format-code.sh # apply formatting & style (run before PR) > ``` > > Generate docs: > > ``` > ./bin/make-stubs.sh # builds the stubs for the C++ module > ./bin/make-docs.sh # build Sphinx HTML docs > ``` > > ### Adding Features > > - Add tests in `tests/` (unit or integration). New functionality without tests may be deferred. > - Keep public APIs documented in docstrings so they surface in Sphinx. > - If a change alters behavior, update existing tests rather than deleting them. Explain rationale in the PR. > > ## 7. Citing > > If you use `pylimer-tools` in published work, please cite it. A minimal BibTeX example: > > ```bibtex > @software{pylimer-tools, > title = {pylimer-tools}, > author = {Bernhard, Tim}, > url = {https://github.com/GenieTim/pylimer-tools}, > year = {2025}, > note = {See CITATION.cff for full metadata and related method references} > } > ``` > > Also cite the specific theoretical / methodological papers corresponding to the components you use (listed in `CITATION.cff`). > > ## 8. Contributing > > We welcome contributions on GitHub via Issues and Pull Requests. > > 1. Discuss larger ideas in an Issue first (helps align scope). > 2. Fork, branch, implement, add tests & docs. > 3. Run formatting and tests locally. > 4. Submit PR referencing the Issue (if any). > > See also: [Code of Conduct](CODE_OF_CONDUCT.md). > > ## 9. Code of Conduct > > We strive for an inclusive, respectful environment. > By participating you agree to uphold the [Code of Conduct](CODE_OF_CONDUCT.md). > Report concerns to the maintainer email specified there. > > ## 10. Acknowledgements > > The authors gratefully acknowledge financial support from the Swiss National Science Foundation (SNSF project 200021_204196). > > ## 11. License > > GPL-3.0-or-later. See [LICENSE](LICENSE). > > This project includes third-party code and libraries under various compatible licenses. See [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) for detailed information about all third-party dependencies and their licenses. > > ## Pronunciation Note > > "pylimer” resembles "polymer”; the playful spelling emphasizes Python integration. 2021-2026, Tim Bernhard ## Pages in this subsection - [Examples](index.html.md): The following gallery contains example scripts demonstrating the usage of various features in pylime... - [Dissipative Particle Dynamics (DPD) Simulations](dpd_simulations/index.html.md): pylimer-tools provides a powerful framework for simulating coarse-grained polymer systems using Diss... - [NOTE](dpd_simulations/plot_dpd_simulation.html.md): Go to the end - [Force Balance, Maximum Entropy Homogenization Procedures](force_balance/index.html.md): pylimer-tools provides three implementations of the Force Balance:cite:p:bernhard_phantom_2025, Maxi... - [NOTE](force_balance/plot_force_balance_2.html.md): Go to the end - [NOTE](force_balance/plot_force_balance.html.md): Go to the end - [NOTE](force_balance/plot_polydispersity_study.html.md): Go to the end - [NOTE](force_balance/plot_fb_deformation_exp.html.md): Go to the end - [NOTE](force_balance/plot_force_relaxation.html.md): Go to the end - [Network Generation](network_generator/index.html.md): pylimer-tools includes a powerful Monte Carlo-based network generator for creating realistic polymer... - [NOTE](network_generator/plot_save_network.html.md): Go to the end - [NOTE](network_generator/plot_simple_crosslinked_network.html.md): Go to the end - [NOTE](network_generator/plot_add_angles.html.md): Go to the end - [NOTE](network_generator/plot_polydisperse_system.html.md): Go to the end - [NOTE](network_generator/plot_multi_component_system.html.md): Go to the end - [NOTE](network_generator/plot_monte_carlo_configuration.html.md): Go to the end - [NOTE](network_generator/plot_vulcanized_network.html.md): Go to the end - [NOTE](network_generator/plot_custom_crosslinking_callback.html.md): Go to the end - [NOTE](network_generator/plot_tetra_peg_network.html.md): Go to the end - [Normal Mode Analysis](normal_mode_analysis/index.html.md): pylimer-tools provides a normal mode analysis (NMA) implementation to predict the loss and storage m... - [NOTE](normal_mode_analysis/plot_normal_mode_analysis.html.md): Go to the end - [File I/O: Readers & Writers](readers_writers/index.html.md): pylimer-tools provides comprehensive support for reading and writing various LAMMPS file formats, en... - [NOTE](readers_writers/plot_unit_conversion.html.md): Go to the end - [NOTE](readers_writers/plot_pylimer_tools_output_reader.html.md): Go to the end - [NOTE](readers_writers/plot_correlated_averages_reader.html.md): Go to the end - [NOTE](readers_writers/plot_histogram_reader.html.md): Go to the end - [NOTE](readers_writers/plot_performance_caching.html.md): Go to the end - [NOTE](readers_writers/plot_convert_trajectory_to_frame.html.md): Go to the end - [NOTE](readers_writers/plot_log_thermo_file_reader.html.md): Go to the end - [NOTE](readers_writers/plot_dump_file_reader.html.md): Go to the end - [NOTE](readers_writers/plot_time_averaged_data_reader.html.md): Go to the end - [NOTE](readers_writers/plot_convert_for_bond_swapping.html.md): Go to the end - [NOTE](readers_writers/plot_data_file_reader.html.md): Go to the end - [NOTE](readers_writers/plot_memory_efficient_dump_file_reading.html.md): Go to the end - [NOTE](readers_writers/plot_data_file_writer.html.md): Go to the end - [Structure Analysis](structure_analysis/index.html.md): pylimer-tools offers various tools to manipulate and analyze the topology of polymer networks. - [NOTE](structure_analysis/plot_decompose_structure.html.md): Go to the end - [NOTE](structure_analysis/plot_loop_analysis.html.md): Go to the end - [NOTE](structure_analysis/plot_end_to_end_distribution.html.md): Go to the end - [NOTE](structure_analysis/plot_structure_analysis.html.md): Go to the end - [Trajectory Analysis](trajectory_analysis/index.html.md): pylimer-tools provides advanced tools for analyzing molecular dynamics trajectories, particularly fo... - [NOTE](trajectory_analysis/plot_trajectory_analysis.html.md): Go to the end - [Computation times](dpd_simulations/sg_execution_times.html.md): **00:03.146** total execution time for 1 file **from auto_examples/dpd_simulations**: - [Computation times](force_balance/sg_execution_times.html.md): **05:31.917** total execution time for 5 files **from auto_examples/force_balance**: - [Computation times](network_generator/sg_execution_times.html.md): **02:20.935** total execution time for 9 files **from auto_examples/network_generator**: - [Computation times](normal_mode_analysis/sg_execution_times.html.md): **00:07.937** total execution time for 1 file **from auto_examples/normal_mode_analysis**: - [Computation times](readers_writers/sg_execution_times.html.md): **00:11.499** total execution time for 13 files **from auto_examples/readers_writers**: - [Computation times](sg_execution_times.html.md): **00:00.000** total execution time for 0 files **from auto_examples**: - [Computation times](structure_analysis/sg_execution_times.html.md): **00:00.231** total execution time for 4 files **from auto_examples/structure_analysis**: - [Computation times](trajectory_analysis/sg_execution_times.html.md): **04:47.601** total execution time for 1 file **from auto_examples/trajectory_analysis**: ## Optional - [Top-level llms.txt](../llms.txt): Complete documentation index.