# grogupy package

## Submodules

## grogupy.core module

Docstring in core.

grogupy.core.build_hh_ss(dh)

  It builds the Hamiltonian and Overlap matrix from the sisl.dh class.

  It restructures the data in the SPIN BOX representation, where NS is the number of supercells and NO is the number of orbitals.

  Args:
    dhsisl.physics.Hamiltonian

      Hamiltonian read in by sisl

  Returns:
    hh(NS, NO, NO) np.array_like

      Hamiltonian in SPIN BOX representation

    ss(NS, NO, NO) np.array_like

      Overlap matrix in SPIN BOX representation

grogupy.core.calc_Vu(H, Tu)

  Calculates the local perturbation in case of a spin rotation.

  Args:
    H(NO, NO) np.array_like

      Hamiltonian

    Tu(NO, NO) array_like

      Rotation around u

  Returns:
    Vu1(NO, NO) np.array_like

      First order perturbed matrix

    Vu2(NO, NO) np.array_like

      Second order perturbed matrix

grogupy.core.onsite_projection(matrix, idx1, idx2)

  It produces the slices of a matrix for the on site projection.

  The slicing is along the last two axes as these contains the orbital indexing.

  Args:
    matrix(…, :, :) np.array_like

      Some matrix

    idxnp.array_like

      The indexes of the orbitals

  Returns:
    np.array_like

      Reduced matrix based on the projection

grogupy.core.parallel_Gk(HK, SK, eran, eset)

  Calculates the Greens function by inversion.

  It calculates the Greens function on all the energy levels at the same time.

  Args:
    HK(NO, NO), np.array_like

      Hamiltonian at a given k point

    SK(NO, NO), np.array_like

      Overlap Matrix at a given k point

    eran(eset) np.array_like

      Energy sample along the contour

    esetint

      Number of energy samples along the contour

  Returns:
    Gk(eset, NO, NO), np.array_like

      Green’s function at a given k point

grogupy.core.remove_clutter_for_save(pairs, magnetic_entities)

  Removes unimportant data from the dictionaries.

  It is used before saving to throw away data that is not needed for post processing.

  Args:
    pairsdict

      Contains all the pair information

    magnetic_entitiesdict

      Contains all the magnetic entity information

  Returns:
    pairsdict

      Contains all the reduced pair information

    magnetic_entitiesdict

      Contains all the reduced magnetic entity information

grogupy.core.sequential_GK(HK, SK, eran, eset)

  Calculates the Greens function by inversion.

  It calculates sequentially over the energy levels.

  Args:
    HK(NO, NO), np.array_like

      Hamiltonian at a given k point

    SK(NO, NO), np.array_like

      Overlap Matrix at a given k point

    eran(eset) np.array_like

      Energy sample along the contour

    esetint

      Number of energy samples along the contour

  Returns:
    Gk(eset, NO, NO), np.array_like

      Green’s function at a given k point

grogupy.core.setup_pairs_and_magnetic_entities(magnetic_entities, pairs, dh, simulation_parameters)

  It creates the complete structure of the dictionaries and fills some basic data.

  It creates orbital indexes, spin box indexes, coordinates and tags for magnetic entities. Furthermore it creates the structures for the energies, the perturbed potentials and the Greens function calculation. It dose the same for the pairs.

  Args:
    pairsdict

      Contains the initial pair information

    magnetic_entitiesdict

      Contains the initial magnetic entity information

    dhsisl.physics.Hamiltonian

      Hamiltonian read in by sisl

    simulation_parametersdict

      A set of parameters from the simulation

  Returns:
    pairsdict

      Contains the initial information and the complete structure

    magnetic_entitiesdict

      Contains the initial information and the complete structure

## grogupy.grogu module

Docstring in grogupy.

grogupy.grogu.main(simulation_parameters, magnetic_entities, pairs)

grogupy.grogu.parse_command_line()

  This function can read input from the command line.

## grogupy.io module

Docstring in io.

grogupy.io.load_pickle(infile)

  Loads the data from the infile with pickle.

  Args:
    infilestr

      Path to infile

  Returns:
    datadict

      A dictionary of data

grogupy.io.print_atoms_and_pairs(magnetic_entities, pairs)

  It prints the pair and magnetic entity information for the grogu out.

  Args:
    magnetic_entitiesdict

      It contains the data on the magnetic entities

    pairsdict

      It contains the data on the pairs

grogupy.io.print_job_description(simulation_parameters)

  It prints the parameters and the description of the job.

  Args:
    simulation_parametersdict

      It contains the simulations parameters

grogupy.io.print_parameters(simulation_parameters)

  It prints the simulation parameters for the grogu out.

  Args:
    simulation_parametersdict

      It contains the simulations parameters

grogupy.io.print_runtime_information(times)

  It prints the runtime information for the grogu out.

  Args:
    timesdict

      It contains the runtime data

grogupy.io.process_input_args(default_arguments, fdf_arguments, command_line_arguments, accepted_inputs=['infile', 'outfile', 'scf_xcf_orientation', 'ref_xcf_orientations', 'kset', 'kdirs', 'ebot', 'eset', 'esetp', 'parallel_solver_for_Gk', 'padawan_mode'])

  It returns the final simulation parameters based on the inputs.

  The merging is done in the order of priority: 1. command line arguments 2. fdf arguments 3. default arguments

  Args:
    default_argumentsdict

      Default arguments from grogupy

    fdf_argumentsdict

      Arguments read from the fdf input file

    command_line_argumentsdict

      Arguments from the command line

  Returns:
    dict

      The final simulation parameters

grogupy.io.read_fdf(path)

  It reads the simulation parameters, magnetic entities and pairs from the fdf.

  Args:
    pathstring

      The path to the .fdf file

  Returns:
    fdf_argumentsdict

      The read input arguments from the fdf file

    magnetic_entitieslist

      It contains the dictionaries associated with the magnetic entities

    pairsdict

      It contains the dictionaries associated with the pair information

grogupy.io.save_pickle(outfile, data)

  Saves the data in the outfile with pickle.

  Args:
    outfilestr

      Path to outfile

    datadict

      Contains the data

## grogupy.magnetism module

Docstring in magnetism.

grogupy.magnetism.blow_up_orbindx(orb_indices)

  Function to blow up orbital indices to make SPIN BOX indices.

  Args:
    orb_indicesnp.array_like

      These are the indices in ORBITAL BOX

  Returns:
    orb_indicesnp.array_like

      These are the indices in SPIN BOX

grogupy.magnetism.calculate_anisotropy_tensor(mag_ent)

  Calculates the renormalized anisotropy tensor from the energies.

  It uses the grogu convention for output.

  Args:
    mag_entdict

      An element from the magnetic entities

  Returns:
    Knp.array_like

      elements of the anisotropy tensor

grogupy.magnetism.calculate_exchange_tensor(pair)

  Calculates the exchange tensor from the energies.

  It produces the isotropic exchange, the relevant elements from the Dzyaloshinskii-Morilla (Dm) tensor, the symmetric-anisotropy and the complete exchange tensor.

  Args:
    pairdict

      An element from the pairs

  Returns:
    J_isofloat

      Isotropic exchange (Tr[J] / 3)

    J_Snp.array_like

      Symmetric-anisotropy (J_S = J - J_iso * I ––> Jxx, Jyy, Jxy, Jxz, Jyz)

    Dnp.array_like

      DM elements (Dx, Dy, Dz)

    Jnp.array_like

      Complete exchange tensor flattened (Jxx, Jxy, Jxz, Jyx, Jyy, Jyz, Jzx, Jzy, Jzz)

grogupy.magnetism.parse_magnetic_entity(dh, atom=None, l=None, **kwargs)

  Function to define orbital indexes of a given magnetic entity.

  Args:
    dhsisl.physics.Hamiltonian

      Hamiltonian from sisl

    atominteger or list of integers, optional

      Defining atom (or atoms) in the unit cell forming the magnetic entity. Defaults to None

    linteger, optional

      Defining the angular momentum channel. Defaults to None

  Returns:
    list

      The orbital indexes of the given magnetic entity

grogupy.magnetism.spin_tracer(M)

  Spin tracer utility.

  This takes an operator with the orbital-spin sequence: orbital 1 up, orbital 1 down, orbital 2 up, orbital 2 down, that is in the SPIN-BOX representation, and extracts orbital dependent Pauli traces.

  Args:
    Mnp.array_like

      Traceable matrix

  Returns:
    dict

      It contains the traced matrix with “x”, “y”, “z” and “c”

## grogupy.utilities module

Docstring in utilities.

grogupy.utilities.RotM(theta, u, eps=1e-10)

  Definition of rotation matrix with angle theta around direction u.

  Args:
    thetafloat

      The angle of rotation

    unp.array_like

      The rotation axis

    epsfloat, optional

      Cutoff for small elements in the resulting matrix. Defaults to 1e-10

  Returns:
    np.array_like

      The rotation matrix

grogupy.utilities.RotMa2b(a, b, eps=1e-10)

  Definition of rotation matrix rotating unit vector a to unit vector b.

  Function returns array R such that R @ a = b holds.

  Args:
    anp.array_like

      First vector

    bnp.array_like

      Second vector

    epsfloat, optional

      Cutoff for small elements in the resulting matrix. Defaults to 1e-10

  Returns:
    np.array_like

      The rotation matrix with the above property

grogupy.utilities.commutator(a, b)

  Shorthand for commutator.

  Commutator of two matrices in the mathematical sense.

  Args:
    anp.array_like

      The first matrix

    bnp.array_like

      The second matrix

  Returns:
    np.array_like

      The commutator of a and b

grogupy.utilities.crossM(u)

  Definition for the cross-product matrix.

  It acts as a cross product with vector u.

  Args:
    ulist or np.array_like

      The second vector in the cross product

  Returns:
    np.array_like

      The matrix that represents teh cross product with a vector

grogupy.utilities.hsk(H, ss, sc_off, k=(0, 0, 0))

  Speed up Hk and Sk generation.

  Calculates the Hamiltonian and the Overlap matrix at a given k point. It is faster that the sisl version.

  Args:
    Hnp.array_like

      Hamiltonian in spin box form

    ssnp.array_like

      Overlap matrix in spin box form

    sc_offlist

      supercell indexes of the Hamiltonian

    ktuple, optional

      The k point where the matrices are set up. Defaults to (0, 0, 0)

  Returns:
    np.array_like

      Hamiltonian at the given k point

    np.array_like

      Overlap matrix at the given k point

grogupy.utilities.int_de_ke(traced, we)

  It numerically integrates the traced matrix.

  It is a wrapper from numpy.trapz and it contains the relevant constants to calculate the energy integral from equation 93 or 96.

  Args:
    tracednp.array_like

      The trace of a matrix or a matrix product

    wefloat

      The weight of a point on the contour

  Returns:
    float

      The energy calculated from the integral formula

grogupy.utilities.make_contour(emin=-20, emax=0.0, enum=42, p=150)

  A more sophisticated contour generator.

  Calculates the parameters for the complex contour integral. It uses the Legendre-Gauss quadrature method. It returns a class that contains the information for the contour integral.

  Args:
    eminint, optional

      Energy minimum of the contour. Defaults to -20

    emaxfloat, optional

      Energy maximum of the contour. Defaults to 0.0, so the Fermi level

    enumint, optional

      Number of sample points along the contour. Defaults to 42

    pint, optional

      Shape parameter that describes the distribution of the sample points. Defaults to 150

  Returns:
    ccont

      Contains all the information for the contour integral

grogupy.utilities.make_kset(dirs='xyz', NUMK=20)

  Simple k-grid generator to sample the Brillouin zone.

  Depending on the value of the dirs argument k sampling in 1,2 or 3 dimensions is generated. If dirs argument does not contain either of x, y or z a kset of a single k-pont at the origin is returned. The total number of k points is the NUMK**(dimensions)

  Args:
    dirsstr, optional

      Directions of the k points in the Brillouin zone. They are the three lattice vectors. Defaults to “xyz”

    NUMKint, optional

      The number of k points in a direction. Defaults to 20

  Returns:
    np.array_like

      An array of k points that uniformly sample the Brillouin zone in the given directions

grogupy.utilities.read_siesta_emin(eigfile)

  It reads the lowest energy level from the siesta run.

  It uses the .EIG file from siesta that contains the eigenvalues.

  Args:
    eigfilestr

      The path to the .EIG file

  Returns:
    float

      The energy minimum

grogupy.utilities.tau_u(u)

  Pauli matrix in direction u.

  Returns the vector u in the basis of the Pauli matrices.

  Args:
    ulist or np.array_like

      The direction

  Returns:
    np.array_like

      Arbitrary direction in the base of the Pauli matrices

## Module contents

Docstring in init.