File Formats

PyPEEC Workflow

Description of the PyPEEC workflow (mesher, viewer, solver, and plotter). The input files (geometry, problem, tolerance, plotter, and viewer) are either in JSON or YAML formats. The output files (voxel and solution) are either in JSON or Pickle formats.

Geometry File Format

• The file_geometry file format is used by the mesher.

• This file contains the definition of the voxel structure.

# mesher type
#   - "voxel" for index arrays
#   - "shape" for 2D vector shapes
#   - "png" for PNG files
#   - "stl" for STL files
"mesh_type": "'voxel' or 'shape' or 'png'  or 'stl'"

# definition of the voxel structure
#   - specific for the different mesher types
#   - format definition is located in separate files
"data_voxelize": {}

# parameters for checking the validity of the point cloud
"data_point":
    # check (or not) the validity of the point cloud
    "check_cloud": true

    # enforce (or not) the validity of all the provided points
    "full_cloud": true

    # 2D array containing the points used for magnetic field evaluation
    #   - the number of points (n_pts) can be zero.
    #   - the array has the following size: (n_pts, 3)
    #   - the points should be located outside the active voxels
    "pts_cloud":
        - [-1.0, +1.0, +1.0]
        - [+1.0, -1.0, +1.0]
        - [+1.0, +1.0, -1.0]
        -
# control the resampling of the voxel structure
"data_resampling":
    # reduce (or not) the voxel structure by removing unused voxels
    "use_reduce": true

    # resample (or not) the voxel structure by subdividing voxels
    "use_resample": true

    # array with resampling factors (x, y, and z directions)
    "resampling_factor": [ 2, 2, 1 ]

# parameters for resolving conflict between domains
"data_conflict":
    # perform (or not) the rule-based conflict resolution
    #   - using the provided resolution rules to remove duplicated voxels
    #   - the resolution rules are applied before the random resolution
    "resolve_rules": true

    # perform (or not) the random conflict resolution
    #   - the duplicated voxels are randomly assigned to a unique domain
    #   - the random resolution is performed after the application of the resolution rules
    "resolve_random": false

    # definition of the conflict resolution rules between domains
    #   - during the voxelization, the same voxel can be assigned to several domains
    #   - the shared voxels are located at the boundaries between domain
    #   - the shared voxels are conflicts and should be assigned to a single domain
    #   - list of dicts with the conflict resolution rules
    #   - optional feature, the list can be empty if no conflict resolution is required
    #   - conflict definition
    #       - domain_resolve: list of domain names where the shared voxels should be removed
    #       - domain_keep: list of domain names where the shared voxels should be kept
    "conflict_rules":
        - {"domain_resolve": ["dom_cond"], "domain_keep": ["dom_src"]}
        - {"domain_resolve": ["dom_cond"], "domain_keep": ["dom_sink"]}

# compute (or not) the connections between the domains
#   - compute the connected components between the voxels
#   - check the connections between the adjacent domains
#   - check the connections between the connected components
"check_integrity": true

# parameters for checking the integrity of the voxel structure
"data_integrity":
    # check if specified domains are connected to each other
    #   - dict of dicts with the connection name and the connection definition
    #   - optional feature, the dict can be empty without having an impact on the results
    #   - check definition
    #       - connected: boolean specified if the specified domains should be connected
    #       - domain_group: list of list of domains where the connections are checked
    #           - the outer list domains are used for the connection checks
    #           - the inner list domains are merged together
    "domain_connected":
        "connected": {"connected": true, "domain_group": [["dom_cond"], ["dom_src"], ["dom_sink"]]}
        "insulated": {"connected": false, "domain_group": [["dom_mag"], ["dom_src", "dom_cond", "dom_sink"]]}

    # check if specified domains are adjacent to each other
    #   - dict of dicts with the connection name and the connection definition
    #   - optional feature, the dict can be empty without having an impact on the results
    #   - check definition
    #       - connected: boolean specified if the specified domains should be connected
    #       - domain_group: list of list of domains where the connections are checked
    #           - the outer list domains are used for the connection checks
    #           - the inner list domains are merged together
    "domain_adjacent":
        "connected": {"connected": true, "domain_group": [["dom_cond"], ["dom_src"], ["dom_sink"]]}
        "insulated": {"connected": false, "domain_group": [["dom_mag"], ["dom_src", "dom_cond", "dom_sink"]]}

Definition from Index Arrays

# voxel definition type ("voxel" for index arrays)
"mesh_type": "voxel"

# definition of the voxel structure
"data_voxelize":
    # definition of the voxel structure
    #   - n: array with the number of voxels (x, y, and z directions)
    #   - d: array with the voxel dimensions (x, y, and z directions)
    #   - c: array with the coordinates of the voxel structure center (x, y, and z directions)
    "param":
        "n": [4, 4, 3]
        "d": [10.0e-3, 10.0e-3, 10.0e-3]
        "c": [0.0, 0.0, 0.0]

    # definition of the voxel indices of the different domains
    #   - dict of arrays with the domain name and the voxel indices
    #   - required information, the dict cannot be empty
    "domain_def":
        "dom_src": [1, 2]
        "dom_cond": [5, 6, 9, 10]
        "dom_sink": [13, 14]
        "dom_mag": [36, 37, 38, 39, 40, 41, 42, 43]

Definition from 2D Vector Shapes

# voxel definition type ("shape" for 2D vector shapes)
"mesh_type": "shape"

# definition of the voxel structure
"data_voxelize":
    # definition of the voxel structure
    #   - dx: voxel dimension for the x direction
    #   - dy: voxel dimension for the y direction
    #   - dz: voxel dimension for the z direction
    #   - cz: coordinates of the voxel structure center for the z direction  (null for centering)
    #   - simplify: tolerance for simplifying the shapes (null for disabling simplification)
    #   - construct: grid size for constructing the shapes (null for default grid size)
    #   - xy_min: array with the lower corner coordinates of the voxel structure
    #       - vector with the x and y coordinates
    #       - if null, the shape bounds are used
    #   - xy_max: array with the upper corner coordinates of the voxel structure
    #       - vector with the x and y coordinates
    #       - if null, the shape bounds are used
    "param":
        "dx": 50.0e-6
        "dy": 50.0e-6
        "dz": 50.0e-6
        "cz": 0.0e-6
        "simplify": 1.0e-6
        "construct": 1.0e-6
        "xy_min": [-20e-3, -20e-3]
        "xy_max": [+20e-3, +20e-3]

    # definition of the layer stack (voxels in the z-direction)
    #   - list of dicts with the definition of the layers
    #   - required information, the list cannot be empty
    #   - layer definition
    #       - n_layer: number of voxels in the z-direction for the layer
    #       - tag_layer: string with the name of the layer
    "layer_stack":
        - {"n_layer": 1, "tag_layer": "mag"}
        - {"n_layer": 5, "tag_layer": "insulation_mag"}
        - {"n_layer": 1, "tag_layer": "cond"}
        - {"n_layer": 5, "tag_layer": "insulation_terminal"}
        - {"n_layer": 1, "tag_layer": "terminal"}

    # definition of the shapes composing the different domains
    #   - dict with the domain name and a list of shape to be assembled
    #   - required information, the dict cannot be empty
    #   - domain definition
    #       - shape_layer: list of layer where the shape is located
    #       - shape_operation: composition operation for assembling the shape ("add" or "sub")
    #       - shape_type: type of the shape ("pad" or "trace" or "polygon")
    #       - shape_data: data containing the shape geometry
    #           - "pad"
    #               - coord: array with the 2D coordinates composing the shape
    #               - diameter: diameter of the pads
    #           - "trace"
    #               - coord: array with the 2D coordinates composing the shape
    #               - width: thickness of the traces
    #           - "polygon"
    #               - coord_shell: array with the 2D coordinates composing the shape
    #               - coord_holes: list of arrays with the 2D coordinates of the holes
    #               - buffer: thickness of the buffer around the polygons
    "geometry_shape":
        "dom_cond":
            -
                "shape_layer": ["cond"]
                "shape_operation": "add"
                "shape_type": "trace"
                "shape_data":
                    "width": 0.5e-3
                    "coord": [[0.0e-3, 0.0e-3], [5.0e-3, 5.0e-3]]
        "dom_mag":
            -
                "shape_layer": ["mag"]
                "shape_operation": "add"
                "shape_type": "polygon"
                "shape_data":
                    "buffer": 0.0
                    "coord_shell": [[0.0e-3, 0.0e-3], [5.0e-3, 0.0e-3], [5.0e-3, 5.0e-3], [0.0e-3, 5.0e-3]]
                    "coord_holes":
                        - [[1.0e-3, 1.0e-3], [2.0e-3, 1.0e-3], [2.0e-3, 2.0e-3], [1.0e-3, 2.0e-3]]
                        - [[3.0e-3, 3.0e-3], [4.0e-3, 3.0e-3], [4.0e-3, 4.0e-3], [3.0e-3, 4.0e-3]]
            -
                "shape_layer": ["mag"]
                "shape_operation": "sub"
                "shape_type": "polygon"
                "shape_data":
                    "buffer": 0.0
                    "coord_shell": [[1.0e-3, 1.0e-3], [3.0e-3, 1.0e-3], [3.0e-3, 3.0e-3], [1.0e-3, 3.0e-3]]
                    "coord_holes": []
        "dom_src":
            -
                "shape_layer": ["insulation_terminal", "terminal"]
                "shape_operation": "add"
                "shape_type": "pad"
                "shape_data":
                    "diameter": 0.7e-3
                    "coord": [[0.0e-3, 0.0e-3]]
        "dom_sink":
            -
                "shape_layer": ["insulation_terminal", "terminal"]
                "shape_operation": "add"
                "shape_type": "pad"
                "shape_data":
                    "diameter": 0.7e-3
                    "coord": [[5.0e-3, 5.0e-3]]

Definition from PNG Files

# voxel definition type ("png" for PNG files)
"mesh_type": "png"

# definition of the voxel structure
"data_voxelize":
    # definition of the voxel structure
    #   - d: array with the voxel dimensions (x, y, and z directions)
    #   - c: array with the coordinates of the voxel structure center (x, y, and z directions)
    #   - size: array with the size of the images (number of voxels in the x and y direction)
    "param":
        "d": [10.0e-3, 10.0e-3, 10.0e-3]
        "c": [0.0, 0.0, 0.0]
        "size": [49, 49]

    # definition of the mapping between the image color and the different domains
    #   - dict with the domain name and the specified colors
    #   - required information, the dict cannot be empty
    #   - the colors are specified with an array of colors (RGBA format)
    "domain_color":
        "dom_src": [[255, 0, 0, 255]]
        "dom_cond": [[0, 0, 0, 255]]
        "dom_sink": [[0, 255, 0, 255]]
        "dom_mag": [[0, 0, 255, 255]]

    # definition of the layer stack (voxels in the z-direction)
    #   - list of dicts with the definition of the layers
    #   - required information, the list cannot be empty
    #   - layer definition
    #       - n_layer: number of voxels in the z-direction for the layer
    #       - filename_list: list of strings with the PNG files defining the layer
    "layer_stack":
        - {"n_layer": 1, "filename_list": ["png/layer_bottom.png"]}
        - {"n_layer": 8, "filename_list": ["png/layer_mid.png"]}
        - {"n_layer": 1, "filename_list": ["png/layer_top.png"]}

Definition from STL Files

# voxel definition type ("stl" for STL files)
"mesh_type": "stl"

# definition of the voxel structure
"data_voxelize":
    # definition of the voxel structure
    #   - d: array with the voxel dimensions (x, y, and z directions)
    #   - xyz_min: array with the lower corner coordinates of the voxel structure
    #       - vector with the x, y, and z coordinates
    #       - if null, the STL mesh bounds are used
    #   - xyz_max: array with the upper corner coordinates of the voxel structure
    #       - vector with the x, y, and z coordinates
    #       - if null, the STL mesh bounds are used
    #   - strict: boolean parameters for checking the STL mesh integrity
    #       - if true, the STL mesh should represent a closed surface
    #       - if false, the surface status of the STL mesh is not checked
    "param":
        "d": [10.0e-3, 10.0e-3, 10.0e-3]
        "xyz_min": [-20e-3, -20e-3, -20e-3]
        "xyz_max": [+20e-3, +20e-3, +20e-3]
        "strict": true

    # definition of the STL files of the different domains
    #   - dict with the domain name and the STL files
    #   - required information, the dict cannot be empty
    #   - domain definition
    #       - list of STL meshes composing the domain
    #       - scale: scaling factor for specifying the unit of the STL meshes (before offsetting)
    #       - offset: array with offsets for translating the STL meshes (after scaling)
    #       - filename: string with the STL filename
    "domain_stl":
        "dom_src": [{"scale": 1.0, "offset": [0.0, 0.0, 0.0], "filename": "stl/dom_src.stl"}]
        "dom_cond": [{"scale": 1.0, "offset": [0.0, 0.0, 0.0], "filename": "stl/dom_cond.stl"}]
        "dom_sink": [{"scale": 1.0, "offset": [0.0, 0.0, 0.0], "filename": "stl/dom_sink.stl"}]
        "dom_mag": [{"scale": 1.0, "offset": [0.0, 0.0, 0.0], "filename": "stl/dom_mag.stl"}]

Problem File Format

• The file_problem file format is used by the solver.

• This file contains the definition of the magnetic problem to be solved.

# material definition
#   - dict of dicts with the material name and the material definition
#   - required information, the dict cannot be empty
#   - electric and magnetic materials can be defined
#   - material definition
#       - domain_list: list of domains with the specified material
#       - material_type: material type ("electric" or "magnetic" or "electromagnetic")
#           - "electric": material with a finite conductivity (with a zero susceptibility)
#           - "magnetic": material with a finite susceptibility (with a zero conductivity)
#           - "electromagnetic": material with a finite susceptibility and permeability
#       - orientation_type: material type ("isotropic" or "anisotropic")
#           - "isotropic": the material parameters are anisotropic
#           - "anisotropic": the material parameters anisotropic
#       - var_type: type of material parameters ("lumped" or "distributed")
#           - "lumped": the material parameters are homogeneous
#           - "distributed": the material parameters are space-dependent
"material_def":
    "mat_electric":
        "domain_list": ["dom_src", "dom_cond", "dom_sink"]
        "material_type": "electric"
        "orientation_type": "isotropic"
        "var_type": "lumped"
    "mat_magnetic":
        "domain_list": ["dom_mag"]
        "material_type": "magnetic"
        "orientation_type": "isotropic"
        "var_type": "lumped"

# source definition
#   - dict of dicts with the source name and the source definition
#   - required information, the dict cannot be empty
#   - sources can only be defined on electric material domains
#   - source definition
#       - domain_list: list of domains with the specified source
#       - source_type: source type ("current" or "voltage")
#       - var_type: type of source parameters ("lumped" or "distributed")
#           - "lumped": the source parameters are homogeneous
#           - "distributed": the source parameters are space-dependent
"source_def":
    "src":
        "domain_list": ["dom_src"]
        "source_type": "current"
        "var_type": "lumped"
    "sink":
        "domain_list": ["dom_sink"]
        "source_type": "voltage"
        "var_type": "lumped"

# definition of the sweep configurations and the sweep parameters
#   - dict of dicts with the material and source parameters
#   - required information, the dict cannot be empty
#   - each dict represents a specific sweep configuration
#   - sweep parameters
#       - init: the dependency is used as an initial guess for the solver
#           - complex (tree-like) dependencies can be used
#           - if null, no initial guess is used for the solver
#       - param: dict with the frequency, material, and source parameters
#           - freq: operating frequency for the problem (DC or AC)
#           - material_val: material parameters
#               - dict of dicts with the material name and the material definition
#               - electric material definition
#                   - rho_re: material real resistivity (should be positive)
#                   - rho_im: material imaginary resistivity (should be positive)
#                   - definition: rho = rho_re + 1j*rho_im
#               - magnetic material definition
#                   - chi_re: material real susceptibility (should be positive)
#                   - chi_im: material imaginary susceptibility (should be positive)
#                   - definition: chi = chi_re - 1j*chi_im
#               - electromagnetic material definition
#                   - rho_re: material real resistivity (should be positive)
#                   - rho_im: material imaginary resistivity (should be positive)
#                   - chi_re: material real susceptibility (should be positive)
#                   - chi_im: material imaginary susceptibility (should be positive)
#                   - definition: rho = rho_re + 1j*rho_im
#                   - definition: chi = chi_re - 1j*chi_im
#               - material value
#                   - "lumped" and "isotropic": scalar
#                       - the material parameters are isotropic
#                       - the same parameters are used for all the voxels
#                       - scalar values are used
#                   - "lumped" and "anisotropic": array
#                       - the array contains the anisotropic parameters
#                       - the same parameters are used for all the voxels
#                       - arrays with following size are used: (3)
#                   - "distributed" and "isotropic": array
#                       - the material parameters are isotropic
#                       - different parameters are used for each voxel
#                       - arrays with following size are used: (n_voxel)
#                   - "distributed" and "anisotropic": 2D array
#                       - the material parameters are anisotropic
#                       - different parameters are used for each voxel
#                       - arrays with following size are used: (n_voxel, 3)
#           - source_val: source parameters
#               - dict of dicts with the source name and the source definition
#               - current source definition
#                   - I_re: current source value (real part)
#                   - I_im: current source value (imaginary part)
#                   - Y_re: current internal admittance (real part)
#                   - Y_im: current internal admittance (imaginary part)
#                   - definition: I = I_re + 1j*I_im
#                   - definition: Y = Y_re + 1j*Y_im
#               - voltage source definition
#                   - V_re: voltage source value (real part)
#                   - V_im: voltage source value (imaginary part)
#                   - Z_re: voltage internal impedance (real part)
#                   - Z_im: voltage internal impedance (imaginary part)
#                   - definition: V = V_re + 1j*V_im
#                   - definition: Z = Z_re + 1j*Z_im
#               - source values
#                   - "lumped": scalar
#                       - the source is using lumped parameters
#                       - the same parameters are used for all the voxels
#                       - scalar values are used
#                   - "distributed": array
#                       - the source is using distributed parameters
#                       - different parameters are used for each voxel
#                       - arrays with following size are used: (n_voxel)
"sweep_solver":
    "sim_dc":
        "init": null
        "param":
            "freq": 0.0
            "material_val":
                "mat_electric": {"rho_re": 1.0e-8, "rho_im": 0.0"}
                "mat_magnetic": {"chi_re": 100.0, "chi_im": 10.0}
            "source_val":
                "src": {"I_re": 1.0, "I_im": 0.0, "Y_re": 2.0, "Y_im": 0.0}
                "sink": {"V_re": 0.0, "V_im": 0.0, "Z_re": 2.0, "Z_im": 0.0}
    "sim_ac":
        "init": sim_dc
        "param":
            "freq": 1.0e+3
            "material_val":
                "mat_electric": {"rho_re": 1.0e-8, "rho_im": 0.0"}
                "mat_magnetic": {"chi_re": 100.0, "chi_im": 10.0}
            "source_val":
                "src": {"I_re": 1.0, "I_im": 0.0, "Y_re": 2.0, "Y_im": 0.0}
                "sink": {"V_re": 0.0, "V_im": 0.0, "Z_re": 2.0, "Z_im": 0.0}

Other File Formats

• The file_tolerance format is documented in examples/config/tolerance.yaml.

• The file_viewer format is documented in examples/config/viewer.yaml.

• The file_plotter format is documented in examples/config/plotter.yaml.