nanocarbon
nanocarbon builds atomistic models of amorphous nanoporous carbon with explicit pores, and measures their structure. A structure is specified by a pore-size distribution (PSD), a pore volume fraction and a carbon density: pores are placed first, drawn from the target PSD up to the target pore fraction; carbon is then grown ring by ring around them up to the target density, and the structure is written out for a molecular-dynamics anneal (LAMMPS), with the pores kept as walls. These properties are therefore inputs of the model, not something read off a melt-quench afterwards. The same post-processing measures any structure, constructed or imported from an MD trajectory: pore-size distribution, porosity, accessible surface and volume, radial distribution function, ring statistics, coordination and pore connectivity. A particle-swarm calibration searches the generation parameters that reproduce experimental targets: density, PSD, porosity, accessible surface area, pore volume and radial distribution function.
A manuscript describing the method, Explicit pore pre-conditioning and inverse design of amorphous nanoporous carbon, is in preparation.
Installation
pip install nanocarbon
Python 3.11 or later. The library depends on numpy, scipy, scikit-learn and
scikit-image only. For the examples and notebooks:
git clone https://github.com/Gemmate-Technologies/nanocarbon.git
cd nanocarbon
uv sync # library + matplotlib, pandas and Jupyter in .venv
Quick start
from nanocarbon import GenerationConfig, run_generation, CarbonStructure
from nanocarbon import post_process as pp, io_functions as io
# Generate one structure and post-process it
cfg = GenerationConfig(box_size=30.0, phi=0.2, pore_mu=5.0, pore_sigma=1.0, max_rho=0.9)
result, structure, pores = run_generation(cfg)
print(result.atoms_number, round(result.achieved_density, 2), result.ring_histogram)
structure.print_LAMMPS("my_structure") # my_structure.data
# Analyze a frame of an MD trajectory
traj = io.import_from_LAMMPS("use_cases/data/harmonic_trajectory.lammpstrj")
s = CarbonStructure.from_LAMMPS_file(traj, frame_index=-1)
print(pp.compute_porosity(s), pp.count_coordination_number(s)["3 bonds"])
Run it from a clone of the repository (the trajectory ships in use_cases/data/); the
generation takes about a minute and a half on a laptop. Every function and class carries a
NumPy-style docstring with shapes and units; lengths are in Angstrom throughout.
use_cases/ holds one runnable example per feature (generation, import, each
post-processing function, a batch, a calibration), listed under
Utilities and examples.
Generation
Pores. PoreStructure.generate packs spheres at random positions up to a target pore
fraction phi, with radii from a Gaussian or a tabulated PSD (.npy, diameter in Angstrom
and value). A tabulated PSD is read as a volume distribution dV/dD by default
(psd_kind="volume"), the convention of adsorption measurements; pass psd_kind="count"
for a number distribution.
Carbon. RingGenerator grows carbon ring by ring from existing bonds: each candidate
ring is oriented by a one-dimensional energy search and accepted if it clears an energy cap
(E_max), the pore exclusion and a merge/reject distance window, so growing fronts stitch
into planes. Ring sizes are drawn from a configurable distribution, with 5-7 defect pairs.
RandomGenerator places single atoms at random under a minimum distance, as an
unstructured baseline. CarbonStructure.generate reruns a generator until the target
density is met and stores the bonds found by distance (pairs closer than 1.704 Angstrom).
Potentials. The energy that gates each ring sums an atom-atom and an atom-pore term:
| Class | Interaction |
|---|---|
HarmonicPotential |
Harmonic bonds, angles and dihedrals, plus 12-6 LJ and growth aids (kcal/mol) |
TersoffPotential |
Tersoff bond order, used as a placement criterion (eV) |
LJPoresPotential |
12-6 LJ wall on the distance to each pore surface (unit of the atoms potential) |
GenerationConfig holds every parameter of a run (its docstring documents each field), and
run_generation(cfg) runs pores, carbon and post-processing in one call, with no file
I/O. The object-level path (generators and potentials built by hand) is shown in
use_cases/generate_*.py.
To LAMMPS. CarbonStructure.print_LAMMPS writes a .data file; PoreStructure.print_LAMMPS
writes each pore as a spherical wall/region LJ wall, cut at its minimum so it only repels
(WCA). Pass the growth's A (converted to the deck's energy unit,
io_functions.WALL_UNIT_TO_EV) and B as LJ_vars to get the wall the structure was grown
against; run_batch does this for you. For a reactive anneal (EDIP, Tersoff),
utilities/convert_to_atomic.py rewrites stored structures in the bond-free atomic style
with the wall depth in eV, and utilities/anneal.in is a starting deck.
Analysis
| Function | Measures | Method |
|---|---|---|
compute_psd |
Pore-size distribution | Largest empty sphere containing each point (Gelb & Gubbins 1999; Bhattacharya & Gubbins 2006), Monte-Carlo on a voxel grid |
compute_porosity |
Void fraction | Monte-Carlo; probe-center fraction by default, geometric with r_probe=0 |
compute_AVA |
Accessible surface area, probe-center and probe-occupiable volumes | Voxel grid, face-connected flood fill from the box faces, marching cubes |
radial_distribution_function |
g(r) | Exact pair counts with a periodic KD-tree |
count_rings |
Ring-size histogram | Primitive rings, those with no shortcut path between two of their atoms (Franzblau 1991) |
count_coordination_number |
Bonds per atom | Stored bond graph |
compute_connectivity |
Mean links per pore | Voronoi pore network with a probe bottleneck test |
Void measures and pair counts are periodic. Accessibility (compute_AVA) is not: the box
faces stand for the outside, so a pore enclosed inside the box does not count as accessible.
Each channel except the connectivity was checked against an independent tool on QMD
reference frames: PSD, surface and volumes against PoreBlazer v4.0
(Sarkisov et al. 2020), g(r) against OVITO
(Stukowski 2010), coordination against
MDAnalysis (Michaud-Agrawal et al. 2011) and rings
against R.I.N.G.S. (Le Roux & Jund 2010).
use_cases/compute_psd.py and compute_rdf.py plot the results next to PoreBlazer and OVITO
references for the same frame.
Batches and calibration
Two command-line verbs read a Python config file:
python -m nanocarbon generate utilities/batch_config.py # a grid of runs, in parallel
python -m nanocarbon optimize utilities/calibrate_config.py # PSO calibration
generate expands a CONDITIONS grid over a base GenerationConfig and runs one structure
per process. Each run writes its configuration, results, arrays, LAMMPS files and JSON
structures; a resubmitted batch skips the runs already on disk, and a run that fails is
recorded with status='generation_error' instead of stopping the batch. Load a batch with
BatchResults.from_run_dir(out_root). optimize searches the parameters in PARAM_BOUNDS
so that the generated structures match the targets in ANCHORS (density, PSD, porosity,
surface area, pore volume, RDF); a polynomial surrogate can propose one extra candidate per
iteration. The calibration checkpoints every iteration and resumes from pso_state.json.
Utilities and examples
utilities/ |
|
|---|---|
batch_config.py, calibrate_config.py |
Config templates for generate and optimize |
run_parallel.slurm |
Runs a batch on one SLURM node |
convert_to_atomic.py |
Stored structures to atomic-style LAMMPS input, wall depth in eV |
anneal.in |
LAMMPS EDIP anneal deck for the converted structures |
analyze_anneal.py |
Anneal trajectory to CSV: coordination every frame, full analysis at the endpoints |
digitise_psd.py |
WebPlotDigitizer CSV export to a PSD .npy |
pso_analysis.ipynb |
Which parameters a calibration constrains, from its search history |
use_cases/ |
|
|---|---|
generate_default.py, generate_custom_potentials.py |
One structure, default or custom potentials |
generate_random.py |
A random-generator structure for a LAMMPS quench |
load_from_lammps.py, load_from_json.py, write_lammps_data.py |
Structure input and output |
compute_psd.py, compute_rdf.py, compute_AVA.py, compute_porosity.py |
One post-processing function each |
compute_connectivity.py, compute_rings_coordination.py |
Same |
batch_gaussian_psd.py, batch_tabular_psd.py |
Small batches on a laptop |
optimize_gaussian_psd.py |
A calibration in a few minutes |
The examples run from any directory, read use_cases/data/ and write to use_cases/output/.
Contributing
Bug reports, questions and suggestions are welcome as GitHub issues or by email to the authors. Pull requests are not accepted.
Authors
- Matteo Alberghini (matteo.alberghini@gemmate-technologies.com)
- Giacomo Pierotti (giacomo.pierotti@gemmate-technologies.com)
License
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0), copyright (c) 2026 Gemmate Technologies s.r.l. See LICENSE. For commercial use, contact Gemmate Technologies.
Metadata
Release files for nanocarbon 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nanocarbon-1.0.0.tar.gz | 104.1 kB | Without provenance | Details for nanocarbon-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nanocarbon-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for nanocarbon-1.0.0-py3-none-any.whl |
Total release size: 213.9 kB
Release files / nanocarbon-1.0.0.tar.gz
| Download URL | nanocarbon-1.0.0.tar.gz |
|---|---|
| Size | 104.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
18375e60b135028b7de13eb3f9110d8734bf30455fdb6ce575d63fb3ca1e1d92
|
|
BLAKE2b-256 checksum How to use checksums |
8dd648a5763c79ddc491ae125faaf9f4247ba31e9557c488496d6caa859de71d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / nanocarbon-1.0.0-py3-none-any.whl
| Download URL | nanocarbon-1.0.0-py3-none-any.whl |
|---|---|
| Size | 109.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
87eecb6b17dcb9ffb22f50ed4200b8b9cc627fcbb400ca9fb00f5b8507fda0f2
|
|
BLAKE2b-256 checksum How to use checksums |
dd15aa5deaff49517b80327cc8c5100bd9f7bf06a15ac027266c24cbb194a2d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for nanocarbon 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.