HCNT Initial Structure Generator

This program creates the initial carbon structure used by the mechanical, thermal, and interfacial simulation codes. It constructs the planar atomic motif, closes the motif through successive 60-degree rotations, resolves coincident seam atoms, applies the prescribed helical rise, repeats the completed structure, and exports the coordinates in XYZ format.

Files

• hcnt_structure_generator.py — organized, documented implementation for routine use.
• HCNT(final).py — original 2018 program retained as the behavioral reference.
• tests/test_equivalence.py — regression comparison that executes both programs and requires identical console output and byte-identical XYZ files.
• docs/ALGORITHM.md — equations, invariants, stage-by-stage behavior, and output contract.
• requirements.txt — Python dependency specification.

Construction sequence

The calculation is divided into six explicit stages:

1. Create the n77 rectangular section.
2. Create the first n75 transition section.
3. Create the widened n55 rectangular section.
4. Create the closing n75 transition section.
5. Rotate the planar motif, remove coincident atoms using the original four-decimal rule, and apply the helical rise.
6. Repeat the closed structure and write hsh<value>.xyz.

The coordinate equations, insertion order, 60-degree rotation matrix, duplicate-removal order, quadrant rules, rise calculation, repetition order, and XYZ formatting are preserved from the original program.

For a precise account of the numerical contract and the compatibility decisions retained from the 2018 source, see docs/ALGORITHM.md.

Parameter conventions

The original construction uses the following conventions:

• s is nonzero.
• n77 and n55 are equal; both may be zero.
• n75 is even; zero is supported.
• RP is the number of repeated structures.
• hsh is the prescribed helical-rise parameter.
• nrot-1 is 4, producing the six sectors used by the closed structure.

These conventions are intentionally documented rather than silently changed or generalized.

Run interactively

Install NumPy and start the readable program:

python -m pip install -r requirements.txt
python hcnt_structure_generator.py

The prompts remain compatible with the source program:

 s=
 n77=
 n75=
 n55=
 hsh=
 RP=
 nrot-1=

The interactive interface retains the original support for trusted numeric expressions. For programmatic use, construct StructureParameters directly instead.

from hcnt_structure_generator import StructureParameters, generate_structure

parameters = StructureParameters(
    s=3,
    n77=1,
    n75=2,
    n55=1,
    helical_rise=1.0,
    repeat_count=1,
    rotation_index=4,
)

result = generate_structure(parameters, verbose=False)
print(result.output_path)

Verify exact behavior

Run the standalone comparison suite from this directory:

python tests/test_equivalence.py

The suite covers standard construction, zero-transition geometry, transition-only geometry, nonzero rise, repeated structures, a larger even transition, and legacy expression input. Every case must match the original console trace and XYZ file exactly.

Research context

This generator provides the starting atomistic geometry used by simulation workflows associated with three research directions:

• Mechanical response: Insight into Geometry-Controlled Mechanical Properties of Spiral Carbon-Based Nanostructures, The Journal of Physical Chemistry C 123(5), 3226–3238 (2019). Related files: geometry-controlled-spiral-carbon-mechanics.
• Thermal transport: Insights into thermal characteristics of spiral carbon-based nanomaterials: From heat transport mechanisms to tunable thermal diode behavior, International Journal of Heat and Mass Transfer 189, 122719 (2022). Related files: spiral-carbon-nanomaterials-thermal.
• Interfacial load transfer: How to characterize interfacial load transfer in spiral carbon-based nanostructure-reinforced nanocomposites: is this a geometry-dependent process?, Physical Chemistry Chemical Physics 21(43), 23880–23892 (2019). Related files: scbn-polyethylene-interfacial-load-transfer.

When the generated structures are used in connection with one of these studies, cite the corresponding article.

Citation

GitHub’s Cite this repository control reads the software metadata from CITATION.cff.