Getting Started

Getting Started#

Tutorial#

As a tutorial, we describe the procedure for generating models and SAMBs.

  1. Download the contents of the examples directory.

  2. Inside the examples directory, run the create_model.py script:

    python -m create_model.py

    # create_model.py
from multipie import create_samb, create_samb_qtdraw, create_samb_matrix

from C3v import C3v  # C3v model input.
from C3v_param import C3v_sel_par  # C3v SAMB selection and parameters.
from graphene import graphene  # graphene model input.
from graphene_param import graphene_sel_par  # graphene SAMB selection and parameters.

verbose = True

# ==================================================
models = [C3v, graphene]  # model input files.
select_inputs = [C3v_sel_par, graphene_sel_par]  # selection and paramter files.

create_samb(models, verbose=verbose)  # create model.
create_samb_matrix(select_inputs, verbose=verbose)  # create full matrix.
create_samb_qtdraw(models, verbose=verbose)  # create full matrix with parameters.

    This will create the C3v and graphene directories. Each directory will contain six files and a samb subdirectory. For C3v, the generated files are:

    • C3v.pkl : Model information file (binary)

    • C3v.tex, C3v.pdf : Summary of the model information

    • C3v.qtdw : QtDraw file of the model structure

    • C3v_matrix.py : Matrix element data of the SAMB

    • C3v_hr.dat : Numerical matrix element data with SAMB weight parameters applied

    • samb : QtDraw files for the SAMB

    The same set of files is generated for graphene.

  3. For details on how to load and analyze the model information binary file, .pkl, see read_model.ipynb

SAMB construction (detail)#

model input file#

The default values of model input file is the following:

# default model input.
default_model = {
    "model": "unknown",
    "group": "C1",
    "cell": {},
    "spinful": False,
    "site": {},
    "bond": [],
    "SAMB_select": {  # select combined SAMB.
        "X": ["Q", "G"],  # type, "Q/G/T/M", []=all.
        "l": [],  # rank, []=all.
        "Gamma": [],  # "IR"=identity, []=all, "..."/["...","..."]=specified irreps.
        "s": [],  # spin, 0/1, []=all.
    },
    "atomic_select": {  # select atomic SAMB.
        "X": [],  # type, "Q/G/T/M", []=all.
        "l": [],  # rank, []=all.
        "Gamma": [],  # "IR"=identity, []=all, "..."/["...","..."]=specified irreps.
        "s": [],  # spin, 0/1, []=all.
    },
    "site_select": {  # select site-cluster SAMB.
        "l": [],  # rank, []=all.
        "Gamma": [],  # "IR"=identity, []=all, "..."/["...","..."]=specified irreps.
    },
    "bond_select": {  # select bond-cluster SAMB.
        "X": [],  # type, "Q/T/M", []=all.
        "l": [],  # rank, []=all.
        "Gamma": [],  # "IR"=identity, []=all, "..."/["...","..."]=specified irreps.
    },
    "toroidal_priority": False,
    "max_neighbor": 10,  # for DFT fitting, e.g. =200.
    "search_cell_range": (-2, 3, -2, 3, -2, 3),  # (a1, a2, a3) range. for DFT fitting, e.g.=(-10, 10, -10, 10, -10, 10).
    "qtdraw": {
        "create": True,  # create QtDraw file ?
        "mode": "standard",  # mode, "standard/detail".
        "view": None,  # [a,b,c], if None, default=[6,5,1].
        #
        "rep_site": True,  # show representative site ?
        "rep_bond": True,  # show representative bond ?
        #
        "max_neighbor": 5,  # max. neighbor to draw.
        "cell_mode": None,  # "off/single/all", if None, single for SG, off for PG.
        "scale": None,  # default or magnification scale.
        "site_radius": 0.07,  # base site radius.
        "bond_width": 0.02,  # base bond width.
    },
    "pdf": {
        "create": True,  # create PDF file ?
        "common_samb": True,  # display common SAMB ?
        "harmonics": True,  # display harmonics ?
        "max_neighbor": 5,  # max. neighbor to write (None: all).
    },
}

You can overwrite whatever you want.

model information files#

Using the following input file, you can construct the model information files by running:

mp_create_samb C3v

This command generates C3v.pkl, C3v.tex, C3v.pdf, and C3v.qtdw. Example input file:

# C3v.py
"""
input file for C3v molecule.
"""
C3v = {
    "model": "C3v",  # name of model.
    "group": "C3v-1",  # name of point group.
    "cell": {"c": 10},  # set large enough interlayer distance.
    #
    "site": {"A": ("[-1/6,-1/6,0]", "s"), "B": ("[-2/3,0,0]", "p")},  # positions of A and B sites and their orbitals.
    "bond": [("A", "A", 1), ("A", "B", 1)],  # nearest-neighbor A-A and B-B bonds.
    #
    "spinful": False,  # spinless.
}

selection and parameter file#

The constructed SAMBs can be selected by selection file:

# selection and parameter example.
selection_paramter = {
    # model pkl name (w/o .pkl).
    "model": "model_pkl_name",
    # selection for SAMB.
    "select": {  # S=site, R=orbital rank.
        "site": [("A", [1, 2])],  # S or (S, [R]).
        "bond": [
            [0, 1, 2]
        ],  # S1;S2, [neighbor], (S1;S2, [neighbor]), (S1;S2, R;R2), (S1;S2, [neighbor]) or (S1;S2, R1;R2, [neighbor]).
        "X": [],  # combined SAMB type Q/G/T/M, []=all.
        "l": [],  # combined SAMB rank, []=all.
        "Gamma": "A1g",  # combined SAMB irreps., e.g., "A1g", ["A1g","A1u"], "IR"=identity irrep., []=all.
        "s": [],  # combined SAMB s=0, 1, []=all.
    },
    # weight for SAMBs, non-specified parameters are zero. (float or sympy const.)
    "parameter": {
        "z1": 1,
        "z2": 1,
    },
}

The typical usage is the following: you first create the SAMBs for all irreps., and then select the desired SAMBs in order to create matrix elements with necessary bases, such as the symmetry-breaking terms in addition to the identity irreps.

matrix element files#

To generate full matrix file, _matrix.py by selection (and _hr.dat for given parameters) file, run:

mp_create_samb_matrix C3v_param

This command generates two files, C3v_matrix.py, and C3v_hr.dat. Example input file:

# C3v_param.py
"""
selection_parameter file for C3v.
if parameter is omitted, no hr.dat file is created.
"""
C3v_sel_par = {
    # model pkl name (w/o .pkl).
    "model": "C3v",
    # selection for SAMB.
    "select": {
        "site": "A",
        "bond": [[1]],
    },
    # weight for SAMBs, non-specified parameters are zero. (float or sympy const.)
    "parameter": {
        "z1": 1,
        "z6": 1,
    },
}

QtDraw SAMB files#

To generate QtDraw files for the constructed SAMB, run:

mp_create_samb_qtdraw C3v graphene

The generated SAMB QtDraw files are saved in the samb directory.

Contents