vibe-sketcherDocumentation

vibesketcher.document.cnt_composites

Representative coated and disordered carbon nanotube fibre composites (#241).

A composite request names one nanotube (explicit chiral indices (n, m), with optional concentric outer walls), a bounded bundle of copies of it, a cell policy, a polymer (repeat units and one chain specification as in vibesketcher.document.polymer_packing), an explicit composition and a seed. The preview returns a derived periodic model under a new ID: the tubes, then the polymer chains grown around them, with provenance that lists each tube’s and each chain’s parent map, both seeds, the stated macroscopic dimensions and the status “unrelaxed representative model”. Nothing is stored until the model is applied, and an applied composite can be undone while it is unchanged (the contract of vibesketcher.document.polymer_packing).

Tubes. A periodic tube is the periodic nanotube cell of vibesketcher.chem.nanotube_cells (the chiral-vector construction of Saito, Dresselhaus and Dresselhaus, Physical Properties of Carbon Nanotubes, 1998, ch. 3) and runs through the cell along c, which is the fibre axis; c is then a whole number of translation periods. A segment tube is the finite, hydrogen-terminated tube of vibesketcher.chem.nanostructures and must fit inside the cell with the stated gap to its own image.

Bundle. hexagonal places the tube axes on a triangular lattice of pitch 2 R + gap, where R is the outer-wall radius (atom centres) and gap the stated intertube atom-centre separation (the default 3.4 angstrom is of the order of the graphite interlayer spacing, 3.35 angstrom); the count lattice points closest to the centre are taken, so incomplete shells are allowed. This is the close-packed bundle of aligned tubes seen in single-wall rope diffraction (A. Thess et al., Science 273, 483-487 (1996), doi:10.1126/science.273.5274.483), stated here as geometry, not fitted. random draws each axis uniformly in a disc of the stated radius, a uniform rotation about the axis and a uniform axial shift, and for segments a tilt with cos(theta) uniform up to max_tilt_deg; a draw closer than the gap to an earlier tube (atom pairs by brute force, periodic images included) or with an atom inside another tube’s cylinder is rejected, and past max_attempts the request is refused. A tilted tube cannot run through a periodic axis and is refused for periodic tubes.

Cells. matrix is a fully periodic orthorhombic box with the bundle at its centre; the polymer fills the space between the tubes and their images. coated_fibre is periodic along c only: a cylindrical coating shell of the stated thickness around the bundle envelope (the largest radial atom distance from the bundle axis), with vacuum outside; with infiltrate false the polymer stays outside the envelope. The chains are grown by vibesketcher.document.polymer_packing.preview() with the tube atoms as a fixed Inclusion: a chain atom may neither overlap a tube atom (the hard-core test of that module) nor lie inside any tube’s outer-wall cylinder, so exclusion is by distance to tube atoms and by the tube interiors, not by boxes.

Composition. Exactly one of a chain count, a target composite density (tubes plus polymer over the cell volume, or over the coated cylinder for a fibre) or a polymer weight fraction sets the number of chains; the achieved values are reported. Macroscopic dimensions (fibre diameters, coating thickness, tube lengths) are recorded as labelled metadata; the atomistic cell is a representative volume element, never the macroscopic object. Nothing is relaxed, and no electrical, mechanical or biological property is inferred.

Module Attributes

EXAMPLES

Requests tied to the issue's sources.

Functions

apply(document, request)

Add the composite model to a copy of document; refusals fail.

example(name)

A copy of a representative example request.

parse_composite(data)

preview(request[, document])

The composite model, its tubes, chains, composition, checks and refusals; nothing stored.

undo(document, identifier)

Remove a composite model again, if it is unchanged since it was built.

Classes

Bundle(*[, count, packing, gap_angstrom, ...])

CompositeCell(*[, kind, lateral_angstrom, ...])

CompositePolymer(*, units, chain[, ...])

The coating or matrix polymer: repeat units and one chain specification.

CompositeRequest(*, identifier[, label, ...])

Composition(*[, chains, ...])

Exactly one of a chain count, a target composite density or a polymer weight fraction.

MacroscopicDimension(*, quantity, value, unit)

A labelled experimental dimension, recorded as metadata and never built.

TubeSpec(*, n[, m, outer_walls, form, periods])

The one nanotube every bundle member copies: (n, m) innermost, optional outer walls.

class vibesketcher.document.cnt_composites.TubeSpec(*, n, m=0, outer_walls=<factory>, form='periodic', periods=4)[source]

Bases: _Model

The one nanotube every bundle member copies: (n, m) innermost, optional outer walls.

Parameters:
n: int
m: int
outer_walls: list[Chirality]
form: Literal['periodic', 'segment']

through the cell along c; segment: finite, hydrogen-terminated.

Type:

periodic

periods: int

per cell (periodic) or per segment.

Type:

Translation periods of the innermost wall

walls()[source]
Return type:

list[Chirality]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.cnt_composites.Bundle(*, count=1, packing='hexagonal', gap_angstrom=3.4, radius_angstrom=None, max_tilt_deg=0.0, max_attempts=5000)[source]

Bases: _Model

Parameters:
  • count (Annotated[int, Ge(ge=1), Le(le=61)])

  • packing (Literal['hexagonal', 'random'])

  • gap_angstrom (Annotated[float, Ge(ge=2.0), Le(le=50), AllowInfNan(allow_inf_nan=False)])

  • radius_angstrom (Annotated[float | None, Ge(ge=0), Le(le=300), AllowInfNan(allow_inf_nan=False)])

  • max_tilt_deg (Annotated[float, Ge(ge=0), Le(le=30), AllowInfNan(allow_inf_nan=False)])

  • max_attempts (Annotated[int, Ge(ge=1), Le(le=1000000)])

count: int
packing: Literal['hexagonal', 'random']
gap_angstrom: float

exact; random: minimum), angstrom.

Type:

Intertube atom-centre separation (hexagonal

radius_angstrom: float | None

axes are drawn uniformly in a disc of this radius about the bundle axis.

Type:

Random

max_tilt_deg: float

the largest tilt of a tube axis from c, degrees.

Type:

Random segments

max_attempts: int
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.cnt_composites.CompositeCell(*, kind='matrix', lateral_angstrom=None, length_angstrom=None, coating_thickness_angstrom=None, infiltrate=False, vacuum_angstrom=10.0)[source]

Bases: _Model

Parameters:
  • kind (Literal['matrix', 'coated_fibre'])

  • lateral_angstrom (tuple[float, float] | None)

  • length_angstrom (Annotated[float | None, Ge(ge=2), Le(le=1000), AllowInfNan(allow_inf_nan=False)])

  • coating_thickness_angstrom (Annotated[float | None, Gt(gt=0), Le(le=200), AllowInfNan(allow_inf_nan=False)])

  • infiltrate (bool)

  • vacuum_angstrom (Annotated[float, Ge(ge=0), Le(le=200), AllowInfNan(allow_inf_nan=False)])

kind: Literal['matrix', 'coated_fibre']
lateral_angstrom: tuple[float, float] | None

the a and b edges (angstrom).

Type:

Matrix

length_angstrom: float | None

the c edge (angstrom); periodic tubes set it.

Type:

Segment tubes

coating_thickness_angstrom: float | None

the coating thickness outside the bundle envelope (angstrom).

Type:

Coated fibre

infiltrate: bool

whether chains may enter the bundle envelope between tubes.

Type:

Coated fibre

vacuum_angstrom: float

vacuum outside the coating on each side (angstrom).

Type:

Coated fibre

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.cnt_composites.Composition(*, chains=None, target_density_g_cm3=None, polymer_weight_fraction=None)[source]

Bases: _Model

Exactly one of a chain count, a target composite density or a polymer weight fraction.

Parameters:
  • chains (Annotated[int | None, Ge(ge=1), Le(le=500)])

  • target_density_g_cm3 (Annotated[float | None, Gt(gt=0), Le(le=5), AllowInfNan(allow_inf_nan=False)])

  • polymer_weight_fraction (Annotated[float | None, Gt(gt=0), Lt(lt=1), AllowInfNan(allow_inf_nan=False)])

chains: int | None
target_density_g_cm3: float | None
polymer_weight_fraction: float | None
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.cnt_composites.CompositePolymer(*, units, chain, torsion_states=<factory>, torsion_jitter_deg=10.0, radii='vdw', radius_overrides=<factory>, collision_scale=0.6, max_attempts=200000, step_retries=8, max_backtracks=200, max_regrowths=20, on_exhausted='refuse')[source]

Bases: _Model

The coating or matrix polymer: repeat units and one chain specification.

The chain’s count is replaced by the number the composition sets. The growth options are those of PolymerPacking.

Parameters:
units: dict[str, pp.RepeatUnit]
chain: pp.ChainSpec
torsion_states: list[pp.TorsionState]
torsion_jitter_deg: float
radii: Literal['vdw', 'covalent']
radius_overrides: dict[str, float]
collision_scale: float
max_attempts: int
step_retries: int
max_backtracks: int
max_regrowths: int
on_exhausted: Literal['refuse', 'partial']
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.cnt_composites.MacroscopicDimension(*, quantity, value, unit, spread=None, source=None, note=None)[source]

Bases: _Model

A labelled experimental dimension, recorded as metadata and never built.

Parameters:
  • quantity (Annotated[str, MinLen(min_length=1), MaxLen(max_length=120)])

  • value (Annotated[float, Gt(gt=0), AllowInfNan(allow_inf_nan=False)])

  • unit (Literal['nm', 'um', 'mm', 'cm', 'm'])

  • spread (Annotated[float | None, Ge(ge=0), AllowInfNan(allow_inf_nan=False)])

  • source (Annotated[str | None, MaxLen(max_length=200)])

  • note (Annotated[str | None, MaxLen(max_length=400)])

quantity: str
value: float
unit: Literal['nm', 'um', 'mm', 'cm', 'm']
spread: float | None
source: str | None
note: str | None
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.cnt_composites.CompositeRequest(*, identifier, label=None, tube, bundle=<factory>, cell, polymer, composition, seed, macroscopic=<factory>, references=<factory>)[source]

Bases: _Model

Parameters:
identifier: str
label: str | None
tube: TubeSpec
bundle: Bundle
cell: CompositeCell
polymer: CompositePolymer
composition: Composition
seed: int
macroscopic: list[MacroscopicDimension]
references: list[str]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

vibesketcher.document.cnt_composites.parse_composite(data)[source]
Parameters:

data (dict[str, Any])

Return type:

CompositeRequest

vibesketcher.document.cnt_composites.preview(request, document=None)[source]

The composite model, its tubes, chains, composition, checks and refusals; nothing stored.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.cnt_composites.apply(document, request)[source]

Add the composite model to a copy of document; refusals fail.

Parameters:
Return type:

Document

vibesketcher.document.cnt_composites.undo(document, identifier)[source]

Remove a composite model again, if it is unchanged since it was built.

Parameters:
Return type:

Document

vibesketcher.document.cnt_composites.EXAMPLES: dict[str, dict[str, Any]] = {'epoxy-thread-disordered': {'bundle': {'count': 3, 'gap_angstrom': 3.4, 'max_tilt_deg': 8.0, 'packing': 'random', 'radius_angstrom': 16.0}, 'cell': {'kind': 'matrix', 'lateral_angstrom': [56.0, 56.0], 'length_angstrom': 30.0}, 'composition': {'polymer_weight_fraction': 0.2}, 'identifier': 'epoxy-thread-cnt', 'label': 'disordered MWCNT segments in an epoxy-infiltrated thread; the EDA/MBDGA cross-linked network is represented by a linear phenoxy surrogate, since crosslinking is not built; illustrative atomistic parameters: the tube indices, bundle size, cell, chain length and packing density are chosen to keep the model small; they are not taken from the paper or its SI', 'macroscopic': [{'quantity': 'MWCNT outer diameter (lower)', 'source': 'doi:10.3390/ma9020068', 'unit': 'nm', 'value': 6}, {'quantity': 'MWCNT outer diameter (upper)', 'source': 'doi:10.3390/ma9020068', 'unit': 'nm', 'value': 20}, {'note': 'stated range 400-500 um; 2-10 walls', 'quantity': 'MWCNT length', 'source': 'doi:10.3390/ma9020068', 'unit': 'um', 'value': 450}, {'note': 'the diameter above which cross-linked thread strength fell; recorded only, no mechanical property is inferred', 'quantity': 'thread diameter threshold', 'source': 'doi:10.3390/ma9020068', 'unit': 'um', 'value': 10}], 'polymer': {'chain': {'length': 2, 'tacticity': 'atactic', 'unit': 'PHX'}, 'units': {'PHX': {'smiles': '[*:1]Oc1ccc(cc1)C(C)(C)c1ccc(cc1)OCC(O)C[*:2]'}}}, 'references': ['doi:10.3390/ma9020068'], 'seed': 2016, 'tube': {'form': 'segment', 'm': 5, 'n': 5, 'outer_walls': [{'m': 10, 'n': 10}], 'periods': 6}}, 'hnbr-coated-microcable': {'bundle': {'count': 3, 'gap_angstrom': 3.4, 'packing': 'hexagonal'}, 'cell': {'coating_thickness_angstrom': 7.0, 'kind': 'coated_fibre'}, 'composition': {'chains': 6}, 'identifier': 'hnbr-coated-cnt', 'label': 'HNBR-coated MWCNT fibre section (coated microcable); illustrative atomistic parameters: the tube indices, bundle size, cell, chain length and packing density are chosen to keep the model small; they are not taken from the paper or its SI', 'macroscopic': [{'note': 'mean of 20 measurements along a 5 m fibre', 'quantity': 'coated fibre diameter', 'source': 'doi:10.3390/nano4040879', 'spread': 3.15, 'unit': 'um', 'value': 26.54}, {'quantity': 'as-spun fibre diameter', 'source': 'doi:10.3390/nano4040879', 'spread': 1.84, 'unit': 'um', 'value': 27.81}, {'note': 'about 4 um, from the coating thickness measurements', 'quantity': 'polymer coating thickness', 'source': 'doi:10.3390/nano4040879', 'unit': 'um', 'value': 4}, {'note': 'typical spinnable array, about 300 um', 'quantity': 'CNT array height', 'source': 'doi:10.3390/nano4040879', 'unit': 'um', 'value': 300}], 'polymer': {'chain': {'arrangement': 'random', 'composition': {'ACN': 0.5, 'HB': 0.5}, 'length': 4, 'tacticity': 'atactic'}, 'units': {'ACN': {'smiles': '[*:1]CC([*:2])C#N'}, 'HB': {'smiles': '*CCCC*'}}}, 'references': ['doi:10.3390/nano4040879'], 'seed': 2014, 'tube': {'m': 5, 'n': 5, 'outer_walls': [{'m': 10, 'n': 10}], 'periods': 4}}, 'resin-embedded-cross-section': {'bundle': {'count': 3, 'gap_angstrom': 3.4, 'packing': 'hexagonal'}, 'cell': {'kind': 'matrix', 'lateral_angstrom': [42.0, 40.0]}, 'composition': {'chains': 4}, 'identifier': 'resin-embedded-cnt', 'label': 'densified MWCNT fibre bundle embedded in a resin matrix (cross section and sidewall exposure); the cured EMBed-812/DDSA/NMA network is represented by a linear phenoxy surrogate, since crosslinking is not built; illustrative atomistic parameters: the tube indices, bundle size, cell, chain length and packing density are chosen to keep the model small; they are not taken from the paper or its SI', 'macroscopic': [{'quantity': 'densified fibre diameter', 'source': 'doi:10.1021/acsaem.9b01723', 'unit': 'um', 'value': 28.22}, {'quantity': 'densified fibre diameter', 'source': 'doi:10.1021/acsaem.9b01723', 'unit': 'um', 'value': 49.14}, {'quantity': 'densified fibre diameter', 'source': 'doi:10.1021/acsaem.9b01723', 'unit': 'um', 'value': 69.45}, {'note': 'microtomed resin film exposing the fibre cross section', 'quantity': 'embedded film thickness', 'source': 'doi:10.1021/acsaem.9b01723', 'unit': 'um', 'value': 40}, {'note': 'upper end of the stated 150-450 um range', 'quantity': 'CNT forest height', 'source': 'doi:10.1021/acsaem.9b01723', 'unit': 'um', 'value': 450}], 'polymer': {'chain': {'length': 2, 'tacticity': 'atactic', 'unit': 'PHX'}, 'units': {'PHX': {'smiles': '[*:1]Oc1ccc(cc1)C(C)(C)c1ccc(cc1)OCC(O)C[*:2]'}}}, 'references': ['doi:10.1021/acsaem.9b01723'], 'seed': 2019, 'tube': {'m': 5, 'n': 5, 'outer_walls': [{'m': 10, 'n': 10}], 'periods': 4}}}

Requests tied to the issue’s sources. Macroscopic dimensions are quoted from the papers’ experimental sections; every atomistic parameter is illustrative.

vibesketcher.document.cnt_composites.example(name)[source]

A copy of a representative example request.

Parameters:

name (str)

Return type:

dict[str, Any]