bentopy—packs stuff in boxes

Bentopy packs molecules to assemble models for molecular dynamics simulations. It uses a voxel-based approach to place molecules into arbitrary geometries, handling systems from simple boxes to cellular-scale models. Additional tools provide efficient solvation and ion placement. Bentopy is force-field agnostic and integrates with existing molecular dynamics workflows. Example systems built with bentopy include entire cell models in the Martini force field and all-atom aerosols.

• Build models at vast scales, quickly.
• Powerful and flexible integration of spatial information.
• Works with any forcefield, from Martini to all-atom.

Information

A number of resources explaining how to build systems using bentopy are available.

• The bentopy wiki gives in-depth descriptions of different commands and concepts.
  • This includes Examples of how different bentopy tools can be used to construct simple and more sophisticated systems.
• The in-depth tutorial: Bentopy: from simple packing to building cellular models. This is an updated version of the tutorial presented at the Martini Workshop 2025.
• A video of Marieke walking through the tutorial.

Citation

If you use bentopy to set up your molecular dynamics system in a publication, please cite our work.

Westendorp MSS, Stevens JA, Brown CM, Dommer AC, Wassenaar TA, Bruininks BMH, and Marrink SJ. Compartment-guided assembly of large-scale molecular models with Bentopy. Protein Science. 2026. e70480. https://doi.org/10.1002/pro.70480

@article{westendorp_stevens_bentopy_2026,
	title = {Compartment-Guided Assembly of Large-Scale Molecular Models with Bentopy},
	doi = {10.1002/pro.70480},
	pages = {e70480},
	journaltitle = {Protein Science},
	author = {Westendorp, Marieke S.S. and
                  Stevens, Jan A. and
                  Brown, Chelsea M. and
                  Dommer, Abigail C. and
                  Wassenaar, Tsjerk A. and
                  Bruininks, Bart M.H. and
                  Marrink, Siewert J.},
	year = 2026,
}

Installation

Bentopy can be installed through pip.

pip install bentopy

For most Linux platforms, pre-built binaries are available and will be installed automatically through pip. For other platforms, such as macOS, a Rust compiler is required. See the detailed installation instructions below.

The bentopy tools

Bentopy currently features five subcommands:

• init: Initialize and validate bentopy input files.
• mask: Create masks based on voxel containments.
• pack: Pack a space and produce a placement list.
• render: Write a structure file and topology based on a placement list.
• solvate: Solvate large models, including very fast ion substitution.
• merge: Merge structure files.

Each subcommand has detailed --help information.

Workflow

A typical bentopy workflow may look like this.

The init and mask tools help prepare the configuration and masks for packing. Based on the input configuration and masks, pack will create a placement list. Using render, you can create a structure file and system topology from the placement list. The merge and solvate tools help you prepare the model for simulation.

What follows is a brief explanation and example invocation of these subcommands. A more detailed walkthrough can be found in the Examples on the wiki.

Pre-processing

init

The init subcommand serves to make setting up a new bentopy project easy. It can be used to create an example configuration file with placeholder values or to validate input files.

bentopy-init example -o input.bent

Read more about the init command.

mask

While simple shapes can be defined directly in a bent file, space masks enable you to capture the complex geometries of curved membranes and large complexes. This allows you to create models based on existing structures or empirical evidence, making sophisticated integrative modeling workflows possible.

The mask subcommand offers a powerful tool for creating these masks. It is built on top of a versatile library for segmenting point clouds and molecular structures, called mdvcontainment.

With mask you can take a structure or point cloud and determine the different compartments within it.

bentopy-mask vesicle.gro -l autofill:masks/inside.npz

Determine the compartments contained by the structure in vesicle.gro and automatically select the innermost compartment (autofill). From that selected compartment, write a mask to masks/inside.npz.

The masks created with bentopy-mask can be imported as a compartment in a bent file.

[ compartment ]
cytoplasm from "masks/inside.npz"

Note that any boolean numpy array stored as a compressed file (npz) of the correct dimensions can function as a valid mask. This makes it possible to create custom scripts and techniques for preparing masks as well.

Packing the structure

pack

The pack subcommand provides the core functionality of bentopy. Given an input configuration file (bent), the input structures will be packed and their positions and orientations are written to a placement list.

bentopy-pack input.bent placements.json

The placement list can be converted to a structure and associated topology using render.

The bent input configuration file

On the wiki, a detailed reference for the bent configuration input file is available.

This is a minimal but complete bent file.

[ general ]
title "Lysozymes in a vesicle"

[ space ]
dimensions 50, 50, 50
resolution 0.5

[ compartments ]
inside from "masks/inside.npz"

[ segments ]
3lyz 300 from "structures/3lyz.pdb" in inside

Provided you have the structure file and the mask, this configuration can be used to place lysozyme structures within a vesicle.

For a more elaborate description of a similar system using an analytical sphere, take a look at Example 1: Simple sphere on the wiki.

Post-processing

render

The result of the packing process is stored as a placement list, which is a json file that describes which structures at what rotations are placed where. In order to create a structure file (and topology file) from this placement list, the render subcommand can be used.

bentopy-render placements.json packed.gro -t topol.top

Render placements.json created by pack to a gro file at packed.gro and write a topology file to topol.top.

This is a separate operation from packing, since the packed systems can become very large. Storing the placement list as an intermediate result decouples the hard task of packing from the simple work of writing it into a structure file.

merge

As the name suggests, merge is a tool for concatenating gro files. Though this is a relatively simple operation, merge provides a convenient way of telling apart different sections of large models by optionally specifying a new residue name for a whole file in the argument list by appending :<residue name> to a file path.

bentopy-merge vesicle.gro:VES packed.gro:LYZ -o merged.gro

Concatenate vesicle.gro and packed.gro into merged.gro, setting the residue names of the lipid vesicle atoms to VES and those of the packed lysozymes to LYZ in the concatenated structure.

solvate

With solvate, large boxes can be solvated quickly and conveniently. Solvate places waters and makes ion substitutions in the same step. It was created to enable cellular-scale solvation and is designed to run very fast while having a low memory footprint. Both atomistic and coarse-grained Martini water placement is supported.

bentopy-solvate -i merged.gro -o solvated.gro -t topol.top \
	-s NA,CL:0.15Ms --charge neutral

Solvate the structure in packed.gro with Martini waters and output the result to solvated.gro. Substitute water residues for ions at 0.15 M NaCl with respect to the remaining solvent¹. Make additional ion substitutions to neutralize the charge of packed.gro based on the provided topology. The number of added waters and ions will be appended to topol.top.

A thorough description of the command is provided in the bentopy-solvate README.

Detailed installation instructions

If pre-built binaries are not available for your platform, you need access to cargo. First, you can check if Rust's build system cargo is installed.

cargo --version

Make sure that this is at least 1.88, the minimum supported rust version for this project. If this is not the case, update using rustup update.

If cargo is not present, you can install it by any means you prefer. Installation through rustup is very easy!

Once cargo is installed, installing bentopy using pip should work.

Install from source

Installing bentopy from source gives you access to the very latest changes. Though the main branch of this project is generally stable, installation from releases is recommended.

To install bentopy from source, you need access to cargo, as described earlier. You can use pip directly to install the project right from the repository.

pip install git+https://github.com/marrink-lab/bentopy

Alternatively, you can clone the repository somewhere, and build from there.

git clone https://github.com/marrink-lab/bentopy
cd bentopy
pip install .

License

Copyright 2024 Marieke S.S. Westendorp, Jan A. Stevens

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Footnotes

1. For molarity with respect to box size, like gmx genion does, use the M suffix. ↩