bentopy 0.2.0a10

Packs stuff in boxes

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.
• Martini Workshop 2025: Bentopy: from simple packing to building cellular models, an in-depth tutorial. (Note that its current state is outdated, and relies on bentopy v0.1.0. An updated tutorial is in progress and will soon be published.)

Citation

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

Westendorp, M.S.S, Stevens, J.A. et al. Bentopy: building molecular dynamics simulations with cellular complexity and scale. In preparation.

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 membrane.gro masks/inside.npz --autofill

Determine the compartments contained by the structure in membrane.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 sphere"

[ space ]
dimensions 100, 100, 100
resolution 0.5

[ compartments ]
ball as sphere at center with diameter 80

[ segments ]
3lyz 2000 from "structures/3lyz.pdb" in ball

Provided you have the structure file, this configuration can be used to create an 80 nm diameter sphere filled with lysozyme structures. This is a minimal version of the system described and explained in 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 structure.gro -t topol.top

Render placements.json created by pack to a gro file at structure.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 chromosome.gro:CHROM membrane.gro:MEM -o chrom_mem.gro

Concatenate chromosome.gro and membrane.gro into chrom_mem.gro, setting the residue names of the chromosome atoms to CHROM and those of the membrane to MEM in the concatenated structure.

solvate

With solvate, large boxes can be solvated quickly and conveniently, with one-step ion substitutions. Solvate enables 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 packed.gro -o solvated.gro \
	-s NA:0.15M -s CL:0.15M --charge 5172 \
	--water-type tip3p

Solvate the structure in packed.gro and output the result to solvated.gro. Substitute water residues for ions at 0.15M NaCl. Compensate the charge of packed.gro with 5172 additional Cl substitutions. Use Tip3P waters (atomistic).

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

Why was bentopy created?

With bentopy, we address the lack of dedicated and generalized tools for packing detailed and MD-ready models while not sacrificing scale or efficiency.

Bentopy was created the goal of improving the workflow for building whole-cell models at the Marrink lab. While tools for preparing individual structures, polymers, and the cell membrane at that large scale were available, the procedure for packing the already crowded cytosol was slow and inflexible. As bentopy was developed, it fulfilled this task excellently, and it quickly became clear that this is a tool that many people had their own creative applications for.

Another problem with setting up large-scale molecular dynamics simulations is addressed by bentopy-solvate. Tools designed for boxes on the order of tens of nanometers start to break down at the mesoscale. With solvate, we introduce a well-considered and thoughtfully optimized tool. The improvement of the solvation stage for coarse-grained models has been excellent, but the improvement in performance and ergonomics is reported to be especially impressive for all-atom solvation.

We want to thank the many fantastic researchers who are creating beautiful models with bentopy for expressing their enthusiasm and providing hands-on feedback.

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.