SystemDesigner

SystemDesigner is an early-stage Python toolkit for building atomistic crystal objects, materializing local object bases, and preparing higher-level assembly workflows. The current design separates local crystal generation from later global organization and from optional derived fields such as magnetization or nuclear scattering length density.

The core idea is hierarchical:

CrystalDesigner
    builds local atomistic crystal objects

AssemblyBaseDesigner
    samples crystal-template parameters
    materializes local objects to disk
    analyzes realized parameter distributions

AssemblyBaseStructurizer
    planned: place local objects in global space

AssemblyBaseMagnetizer
    planned: attach local magnetic vector fields

AssemblyBaseNucleizer
    planned: attach local nuclear SLD fields

Current Status

Implemented:

• Create one- or multi-atom crystal bases as structured dictionaries.
• Repeat crystal bases in simple lattice directions.
• Apply coordinate operators such as centering and implicit cuts.
• Define crystal templates, currently including spherical simple-cubic nanoparticles.
• Define assembly-base parameter distributions:
  • constant
  • uniform
  • normal
  • lognormal
• Materialize sampled local objects to:

RealSpaceData/
    Local_Objects/
        Object_1/
            pos.csv
            meta.csv
            atomtype.csv
        Object_2/
            ...

• Analyze realized template parameters from meta.csv.
• Plot realized parameter histograms with expected density overlays when distribution metadata is available.

Planned:

• AssemblyBaseStructurizer: generate StructData.csv with global object centers and, later, object rotations.
• AssemblyBaseMagnetizer: generate MagData/Object_i/m_k.csv with local x, y, z, mx, my, mz data.
• AssemblyBaseNucleizer: generate local nuclear SLD data without modifying the original object geometry.
• Export or simulation-builder layer that combines local object data, StructData.csv, and optional magnetic/nuclear data.

Project Layout

SystemDesigner/
    CrystalDesigner/
        CrystalBase.py
        CrystalRepeater.py
        CrystalOperator.py
        CrystalTemplates.py
        CrystalPlot.py
        Examples/
            Example1.py
            Example2.py

    AssemblyBaseDesigner/
        AssemblyBase.py
        AssemblyBaseTemplates.py
        AssemblyBaseWriter.py
        AssemblyBaseAnalyzer.py
        AssemblyBasePlot.py
        Examples/
            Example1.py

    AssemblyBaseStructurizer/
    AssemblyBaseMagnetizer/
    AssemblyBaseNucleizer/

Requirements

The code currently expects a Python environment with at least:

• numpy
• matplotlib

No package installation is required during development. Run examples from the repository root with Python's module mode (python -m ...). This keeps the examples in their corresponding designer folders while preserving clean package imports.

Quick Start

Run the AssemblyBaseDesigner example:

python -m SystemDesigner.AssemblyBaseDesigner.Examples.Example1

This generates a dilute local object base of spherical Fe nanoparticles with a Gaussian radius distribution:

AssemblyExample1/
    RealSpaceData/
        Local_Objects/
        parameter_table.csv
        parameter_distributions.png

The example uses:

write_gaussian_spherical_nanoparticle_base(
    R_mean=10.0,
    R_std=3.0,
    a=1.0,
    atomtype="Fe",
    n_objects=500,
    output_dir="AssemblyExample1",
    seed=123,
)

CrystalDesigner Example

The crystal example builds a simple-cubic Fe sphere and plots it:

python -m SystemDesigner.CrystalDesigner.Examples.Example1

This example opens a Matplotlib window via plt.show().

The cylindrical crystal-cut example can be run with:

python -m SystemDesigner.CrystalDesigner.Examples.Example2

Data Model

Local Crystal Object

Local objects are stored before any global arrangement is applied.

pos.csv:

x,y,z
...

atomtype.csv:

atom_index,atomtype
0,Fe
...

meta.csv:

key,value
object_id,1
template_name,sc_sphere_crystal
n_atoms,1419
template_param.R,7.03
template_param_distribution.R.distribution,normal
template_param_distribution.R.mean,10.0
template_param_distribution.R.sigma,3.0

Future Global Assembly

The planned AssemblyBaseStructurizer should create a separate StructData.csv, for example with object centers and rotations. This keeps local object geometry independent from global organization.

Design Principles

• Local crystal construction and global assembly organization are separate.
• Assembly bases store sampled template parameters and materialized local objects, not global positions.
• Magnetic and nuclear derived data should be added in orthogonal branches without mutating the base geometry.
• Templates hide lower-level crystal-template details from examples and user scripts.

Development Notes

• The codebase is still experimental and API names may change.
• AssemblyBaseAnalyzer can read both the new RealSpaceData/Local_Objects layout and legacy RealSpaceData/Objects datasets.
• gen_structure.py is retained as a reference script and is not part of the current cleaned SystemDesigner API.