pyNIBS 0.2024.8__py3-none-any.whl → 0.2026.1__py3-none-any.whl

pynibs/{coil.py → coil/coil.py}

@@ -1,18 +1,15 @@
-"""
-All functions to operate on TMS coils go here, for example to create ``.xdmf`` files to visualize coil positions.
-"""
 import os
+import tqdm
 import copy
 import math
 import h5py
-import shutil
 import random
+import shutil
 import itertools
-import pandas as pd
 import numpy as np
-import matplotlib.pyplot as plt
 from scipy.spatial import Delaunay
 from collections import OrderedDict
+from matplotlib import pyplot as plt
 
 import pynibs
 
@@ -59,7 +56,7 @@ def check_coil_position(points, hull):
     valid : bool
         Validity of coil position:
         TRUE: valid
-        FALSE: unvalid
+        FALSE: invalid
     """
     # make Delaunay grid if not already passed
     if not isinstance(hull, Delaunay):
@@ -117,7 +114,7 @@ def calc_coil_transformation_matrix(LOC_mean, ORI_mean, LOC_var, ORI_var, V):
             \\end{bmatrix}
     """
     # calculate rotation matrix for angle variation (angle_var in deg)
-    rotation_matrix = pynibs.euler_angles_to_rotation_matrix(ORI_var * np.pi / 180.)
+    rotation_matrix = pynibs.util.rotations.euler_angles_to_rotation_matrix(ORI_var * np.pi / 180.)
 
     # determine new orientation
     ori = np.dot(ORI_mean, rotation_matrix)
@@ -196,7 +193,7 @@ def calc_coil_position_pdf(fn_rescon=None, fn_simpos=None, fn_exp=None, orientat
         folder_pdfplots = ''
 
     if fn_rescon and fn_simpos:
-        positions_all, conditions, position_list, _, _ = pynibs.read_exp_stimulations(fn_rescon, fn_simpos)
+        positions_all, conditions, position_list, _, _ = pynibs.expio.read_exp_stimulations(fn_rescon, fn_simpos)
 
         # sort POSITIONS according to CONDITIONS, idx_con is alphabetically sorted, first index of condition[*]
         # appeareance
@@ -382,7 +379,8 @@ def test_coil_position_gpc(parameters):
             triangles = node_number_list[elm_type == 2, 0:3]
 
         triangles = triangles[triangles_regions == 5]
-        surface_points = pynibs.unique_rows(np.reshape(points[triangles], (3 * triangles.shape[0], 3)))
+        surface_points = pynibs.util.utils.unique_rows(np.reshape(points[triangles],
+                                                                  (3 * triangles.shape[0], 3)))
         limits_scaling_factor = .1
 
         # Generate Delaunay triangulation object
@@ -501,12 +499,12 @@ def get_invalid_coil_parameters(param_dict, coil_position_mean, svd_v, del_obj,
     limits_theta = param_dict['theta']['limits']
     limits_phi = param_dict['phi']['limits']
 
-    limits_pos_x = pynibs.add_center(limits_pos_x)
-    limits_pos_y = pynibs.add_center(limits_pos_y)
-    limits_pos_z = pynibs.add_center(limits_pos_z)
-    limits_psi = pynibs.add_center(limits_psi)
-    limits_theta = pynibs.add_center(limits_theta)
-    limits_phi = pynibs.add_center(limits_phi)
+    limits_pos_x = pynibs.util.utils.add_center(limits_pos_x)
+    limits_pos_y = pynibs.util.utils.add_center(limits_pos_y)
+    limits_pos_z = pynibs.util.utils.add_center(limits_pos_z)
+    limits_psi = pynibs.util.utils.add_center(limits_psi)
+    limits_theta = pynibs.util.utils.add_center(limits_theta)
+    limits_phi = pynibs.util.utils.add_center(limits_phi)
 
     temp_list = [[0, 1, 2], [0, 1, 2], [0, 1, 2], [0, 1, 2], [0, 1, 2], [0, 1, 2]]
     combinations = list(itertools.product(*temp_list))
@@ -582,513 +580,10 @@ def get_invalid_coil_parameters(param_dict, coil_position_mean, svd_v, del_obj,
     return fail_params
 
 
-def create_stimsite_hdf5(fn_exp, fn_hdf, conditions_selected=None, sep="_", merge_sites=False, fix_angles=False,
-                         data_dict=None, conditions_ignored=None):
-    """
-    Reads results_conditions and creates an hdf5/xdmf pair with condition-wise centers of stimulation sites and
-    coil directions as data.
-
-    Parameters
-    ----------
-    fn_exp : str
-        Path to results.csv.
-    fn_hdf : str
-        Path where to write file. Gets overridden if already existing.
-    conditions_selected : str or list of str, optional
-        List of conditions returned by the function, the others are omitted.
-        If None, all conditions are returned.
-    sep: str, default: "_"
-        Separator between condition label and angle (e.g. M1_0, or M1-0).
-    merge_sites : bool
-        If true, only one coil center per site is generated.
-    fix_angles : bool
-        rename 22.5 -> 0, 0 -> -45, 67.5 -> 90, 90 -> 135.
-    data_dict : dict ofnp.ndarray of float [n_stimsites] (optional), default: None
-        Dictionary containing data corresponding to the stimulation sites (keys).
-    conditions_ignored : str or list of str, optional
-        Conditions, which are not going to be included in the plot.
-
-    Returns
-    -------
-    <Files> : hdf5/xdmf file pair
-        Contains information about condition-wise stimulation sites and coil directions (fn_hdf)
-
-    Example
-    -------
-    .. code-block:: python
-
-        pynibs.create_stimsite_hdf5('/exp/1/experiment_corrected.csv',
-                                    '/stimsite', True, True)
-    """
-    assert not fn_hdf.endswith('/')
-
-    exp = pynibs.read_csv(fn_exp)
-
-    exp_cond = pynibs.sort_by_condition(exp, conditions_selected=conditions_selected)  # []
-
-    # get the unique conditions in the correct order
-    conds = [c['condition'][0] for c in exp_cond]
-
-    # remove conds
-    conds_temp = []
-    exp_cond_temp = []
-
-    if type(conditions_ignored) is not list:
-        conditions_ignored = [conditions_ignored]
-
-    for i_c, c in enumerate(conds):
-        ignore = False
-        for ci in list(conditions_ignored):
-            if c == ci:
-                ignore = True
-
-        if not ignore:
-            conds_temp.append(conds[i_c])
-            exp_cond_temp.append(exp_cond[i_c])
-
-    exp_cond = exp_cond_temp
-    conds = conds_temp
-
-    # hardcoded row #3 is condition
-    cond_idx = np.linspace(0, len(exp_cond), 1)[:, np.newaxis]
-
-    centers = []
-    m0 = []
-    m1 = []
-    m2 = []
-
-    for i_cond in range(len(exp_cond)):
-        centers.append(exp_cond[i_cond]['coil_mean_matrix'][0][0:3, 3])
-        m0.append(exp_cond[i_cond]['coil_mean_matrix'][0][0:3, 0])
-        m1.append(exp_cond[i_cond]['coil_mean_matrix'][0][0:3, 1])
-        m2.append(exp_cond[i_cond]['coil_mean_matrix'][0][0:3, 2])
-
-    # split conds to angles and sites: M1_90 -> M1, 90
-    angles = np.array([sp.split(sep)[-1] for sp in conds]).astype(np.float64)
-    sites = np.array([sp.split(sep)[0] for sp in conds])
-    sites_unique = np.unique(sites)
-
-    # average the center positions of a stimulation site over all orientations
-    if merge_sites:
-
-        # generate sites dict
-        centers_sites = dict()
-
-        for site in sites_unique:
-            centers_sites[site] = []
-
-        # gather all orientations and put them to the corresponding sites
-        for i_cond, site in enumerate(sites):
-            centers_sites[site].append(exp_cond[i_cond]['coil_mean_matrix'][0][0:3, 3])
-
-        # determine average position over all orientations for each site
-        for site in sites_unique:
-            centers_sites[site] = np.mean(np.vstack(centers_sites[site]), axis=0)
-
-        # write it back to centers
-        for i_cond, site in enumerate(sites):
-            centers[i_cond] = centers_sites[site]
-
-    centers = np.vstack(centers)
-    m0 = np.vstack(m0)
-    m1 = np.vstack(m1)
-    m2 = np.vstack(m2)
-
-    # enumerate sites, as paraview does not plot string array data
-    sites_idx = np.array(list(range(len(sites))))[:, np.newaxis]
-
-    angles[angles[:] == 675.] = 67.5
-    angles[angles[:] == 225.] = 22.5
-
-    if fix_angles:
-        # rename wrong angle names
-        angles_cor = np.copy(angles)
-        angles_cor[angles == 0] = -45.
-        angles_cor[angles == 22.5] = 0.
-        angles_cor[angles == 67.5] = 90.
-        angles_cor[angles == 90] = 135.
-        angles = angles_cor
-
-    # write hdf5 file
-    if not fn_hdf.endswith('.hdf5'):
-        fn_hdf += '.hdf5'
-    f = h5py.File(fn_hdf, 'w')
-    f.create_dataset('centers', data=centers.astype(np.float64))
-    f.create_dataset('m0', data=m0.astype(np.float64))
-    f.create_dataset('m1', data=m1.astype(np.float64))
-    f.create_dataset('m2', data=m2.astype(np.float64))
-    f.create_dataset('cond', data=np.string_(conds))  # this is a string array, not xdmf compatible
-    f.create_dataset('cond_idx', data=cond_idx)
-    f.create_dataset('angles', data=angles)
-    f.create_dataset('sites', data=np.string_(sites))  # this is a string array, not xdmf compatible
-    f.create_dataset('sites_idx', data=sites_idx)
-
-    data = None
-    if data_dict is not None:
-        data = np.zeros((len(list(data_dict.keys())), 1))
-        for i_data, cond in enumerate(conds):
-            data[i_data, 0] = data_dict[cond]
-        f.create_dataset('data', data=data)
-    f.close()
-
-    # write .xdmf file
-    f = open(fn_hdf[:-4] + 'xdmf', 'w')
-    fn_hdf = os.path.basename(fn_hdf)  # relative links
-
-    # header
-    f.write('<?xml version="1.0"?>\n')
-    f.write('<!DOCTYPE Xdmf SYSTEM "Xdmf.dtd" []>\n')
-    f.write('<Xdmf Version="2.0" xmlns:xi="http://www.w3.org/2001/XInclude">\n')
-    f.write('<Domain>\n')
-    f.write('<Grid\nCollectionType="Spatial"\nGridType="Collection"\nName="Collection">\n')
-
-    # one grid for coil dipole nodes...store data hdf5.
-    #######################################################
-    f.write('<Grid Name="stimsites" GridType="Uniform">\n')
-    f.write('<Topology NumberOfElements="' + str(centers.shape[0]) +
-            '" TopologyType="Polyvertex" Name="Tri">\n')
-    f.write('<DataItem Format="XML" Dimensions="' + str(centers.shape[0]) + ' 1">\n')
-    # f.write(hdf5_fn + ':' + path + '/triangle_number_list\n')
-    np.savetxt(f, list(range(centers.shape[0])), fmt='%d', delimiter=' ')  # 1 2 3 4 ... N_Points
-    f.write('</DataItem>\n')
-    f.write('</Topology>\n')
-
-    # nodes
-    f.write('<Geometry GeometryType="XYZ">\n')
-    f.write('<DataItem Format="HDF" Dimensions="' + str(centers.shape[0]) + ' 3">\n')
-    f.write(fn_hdf + ':' + '/centers\n')
-    f.write('</DataItem>\n')
-    f.write('</Geometry>\n')
-
-    # data
-    # dipole magnitude
-    # the 4 vectors
-    for i in range(3):
-        f.write('<Attribute Name="dir_' + str(i) + '" AttributeType="Vector" Center="Cell">\n')
-        f.write('<DataItem Format="HDF" Dimensions="' + str(centers.shape[0]) + ' 3">\n')
-        f.write(fn_hdf + ':' + '/m' + str(i) + '\n')
-        f.write('</DataItem>\n')
-        f.write('</Attribute>\n\n')
-
-    #  angles
-    f.write('<Attribute Name="angles" AttributeType="Scalar" Center="Cell">\n')
-    f.write('<DataItem Format="HDF" Dimensions="' + str(centers.shape[0]) + ' 1">\n')
-    f.write(fn_hdf + ':' + '/angles\n')
-    f.write('</DataItem>\n')
-    f.write('</Attribute>\n\n')
-
-    #  data
-    if data_dict is not None:
-        f.write('<Attribute Name="data" AttributeType="Scalar" Center="Cell">\n')
-        f.write('<DataItem Format="HDF" Dimensions="' + str(data.shape[0]) + ' 1">\n')
-        f.write(fn_hdf + ':' + '/data\n')
-        f.write('</DataItem>\n')
-        f.write('</Attribute>\n\n')
-
-    # site idx
-    f.write('<Attribute Name="sites_idx" AttributeType="Scalar" Center="Cell">\n')
-    f.write('<DataItem Format="HDF" Dimensions="' + str(centers.shape[0]) + ' 1">\n')
-    f.write(fn_hdf + ':' + '/sites_idx\n')
-    f.write('</DataItem>\n')
-    f.write('</Attribute>\n\n')
-
-    f.write('</Grid>\n')
-    # end coil dipole data
-
-    # footer
-    f.write('</Grid>\n')
-    f.write('</Domain>\n')
-    f.write('</Xdmf>\n')
-    f.close()
-
-
-def create_stimsite_from_list(fn_hdf, poslist, datanames=None, data=None, overwrite=False):
-    """
-    This takes a list of matsimnibs-style coil position and orientations and creates an .hdf5 + .xdmf tuple
-    for all positions.
-
-    Centers and coil orientations are written to disk, with optional data for each coil configuration.
-
-    Parameters
-    ----------
-    fn_hdf: str
-        Filename for the .hdf5 file. The .xdmf is saved with the same basename.
-        Folder should already exist.
-    poslist: list of np.ndarray
-        (4,4) Positions.
-    datanames: str or list of str, optional
-        Dataset names for ``data``.
-    data: np.ndarray, optional
-        Dataset array with shape = ``(len(poslist.pos), len(datanames())``.
-    overwrite : bool, defaul: False
-        Overwrite existing files.
-    """
-    centers = []
-    m0 = []
-    m1 = []
-    m2 = []
-    if data is not None:
-        assert isinstance(data, np.ndarray)
-
-    for lst in poslist:
-        centers.append(lst[0:3, 3])
-        m0.append(lst[0:3, 0])
-        m1.append(lst[0:3, 1])
-        m2.append(lst[0:3, 2])
-
-    centers = np.vstack(centers)
-    m0 = np.vstack(m0)
-    m1 = np.vstack(m1)
-    m2 = np.vstack(m2)
-
-    write_coil_pos_hdf5(fn_hdf, centers, m0, m1, m2, datanames=datanames, data=data, overwrite=overwrite)
-
-
-def create_stimsite_from_tmslist(fn_hdf, poslist, datanames=None, data=None, overwrite=False):
-    """
-    This takes a :py:class:simnibs.sim_struct.TMSLIST from simnibs and creates an .hdf5 + .xdmf tuple for all positions.
-
-    Centers and coil orientations are written to disk, with optional data for each coil configuration.
-
-    Parameters
-    ----------
-    fn_hdf: str
-        Filename for the .hdf5 file. The .xdmf is saved with the same basename.
-        Folder should already exist.
-    poslist: simnibs.sim_struct.TMSLIST
-        poslist.pos[*].matsimnibs have to be set.
-    datanames: str or list of str, optional
-        Dataset names for ``data``.
-    data: np.ndarray, optional
-        Dataset array with shape = ``(len(poslist.pos), len(datanames())``.
-    overwrite : bool, default: False
-        Overwrite existing files
-    """
-    centers = []
-    m0 = []
-    m1 = []
-    m2 = []
-    assert poslist.pos
-    if data is not None:
-        assert isinstance(data, np.ndarray)
-    for pos in poslist.pos:
-        assert pos.matsimnibs is not None
-        pos.matsimnibs = np.array(pos.matsimnibs)
-        centers.append(pos.matsimnibs[0:3, 3])
-        m0.append(pos.matsimnibs[0:3, 0])
-        m1.append(pos.matsimnibs[0:3, 1])
-        m2.append(pos.matsimnibs[0:3, 2])
-
-    centers = np.vstack(centers)
-    m0 = np.vstack(m0)
-    m1 = np.vstack(m1)
-    m2 = np.vstack(m2)
-
-    write_coil_pos_hdf5(fn_hdf, centers, m0, m1, m2, datanames=datanames, data=data, overwrite=overwrite)
-
-
-def create_stimsite_from_exp_hdf5(fn_exp, fn_hdf, datanames=None, data=None, overwrite=False):
-    """
-    This takes an experiment.hdf5 file and creates an .hdf5 + .xdmf tuple for all coil positions for visualization.
-
-    Parameters
-    ----------
-    fn_exp : str
-        Path to experiment.hdf5
-    fn_hdf : str
-        Filename for the resulting .hdf5 file. The .xdmf is saved with the same basename.
-        Folder should already exist.
-    datanames : str or list of str, optional
-        Dataset names for ``data``
-    data : np.ndarray, optional
-        Dataset array with shape = ``(len(poslist.pos), len(datanames())``.
-    overwrite : bool, default: False
-        Overwrite existing files.
-    """
-    df_stim = pd.read_hdf(fn_exp, "stim_data")
-
-    matsimnibs = np.zeros((4, 4, df_stim.shape[0]))
-
-    for i in range(df_stim.shape[0]):
-        matsimnibs[:, :, i] = df_stim["coil_mean"].iloc[i]
-
-    create_stimsite_from_matsimnibs(fn_hdf=fn_hdf,
-                                    matsimnibs=matsimnibs,
-                                    datanames=datanames,
-                                    data=data,
-                                    overwrite=overwrite)
-
-
-def create_stimsite_from_matsimnibs(fn_hdf, matsimnibs, datanames=None, data=None, overwrite=False):
-    """
-    This takes a matsimnibs array and creates an .hdf5 + .xdmf tuple for all coil positions for visualization.
-
-    Centers and coil orientations are written disk.
-
-    Parameters
-    ----------
-    fn_hdf: str
-        Filename for the .hdf5 file. The .xdmf is saved with the same basename.
-        Folder should already exist.
-    matsimnibs: np.ndarray
-        (4, 4, n_pos)
-        Matsimnibs matrices containing the coil orientation (x,y,z) and position (p)
-
-        .. math::
-            \\begin{bmatrix}
-            | & | & | & | \\\\
-            x & y & z & p \\\\
-            | & | & | & | \\\\
-            0 & 0 & 0 & 1 \\\\
-            \\end{bmatrix}
-    datanames: str or list of str, optional
-        Dataset names for ``data``.
-    data: np.ndarray, optional
-        (len(poslist.pos), len(datanames).
-    overwrite : bool, default: False
-        Overwrite existing files.
-    """
-    matsimnibs = np.atleast_3d(matsimnibs)
-    n_pos = matsimnibs.shape[2]
-    centers = np.zeros((n_pos, 3))
-    m0 = np.zeros((n_pos, 3))
-    m1 = np.zeros((n_pos, 3))
-    m2 = np.zeros((n_pos, 3))
-    if data is not None:
-        assert isinstance(data, np.ndarray)
-
-    for i in range(matsimnibs.shape[2]):
-        centers[i, :] = matsimnibs[0:3, 3, i]
-        m0[i, :] = matsimnibs[0:3, 0, i]
-        m1[i, :] = matsimnibs[0:3, 1, i]
-        m2[i, :] = matsimnibs[0:3, 2, i]
-
-    write_coil_pos_hdf5(fn_hdf, centers, m0, m1, m2, datanames=datanames, data=data, overwrite=overwrite)
-
-
-def write_coil_pos_hdf5(fn_hdf, centers, m0, m1, m2, datanames=None, data=None, overwrite=False):
-    """
-    Creates a ``.hdf5`` + ``.xdmf`` file tuple for all coil positions.
-    Coil centers and coil orientations are saved, and - optionally - data for each position if ``data`` and
-    ``datanames`` are provided.
-
-    Parameters
-    ----------
-    fn_hdf : str
-        Filename for the .hdf5 file. The .xdmf is saved with the same basename.
-        Folder should already exist.
-    centers : np.ndarray of float
-        (n_pos, 3) Coil positions.
-    m0 : np.ndarray of float
-        (n_pos, 3) Coil orientation x-axis (looking at the active (patient) side of the coil pointing to the right).
-    m1 : np.ndarray of float
-        (n_pos, 3) Coil orientation y-axis (looking at the active side of the coil pointing up away from the handle).
-    m2 : np.ndarray of float
-        (n_pos, 3) Coil orientation z-axis (looking at the active (patient) side of the coil pointing to the patient).
-    datanames : str or list of str, optional
-        (n_data) Dataset names for ``data``
-    data : np.ndarray, optional
-        (n_pos, n_data) Dataset array with (len(poslist.pos), len(datanames()).
-    overwrite : bool, default: False
-        Overwrite existing files.
-    """
-    n_pos = centers.shape[0]
-    if isinstance(datanames, str):
-        datanames = [datanames]
-
-    if data is not None:
-        if datanames is None:
-            raise ValueError("Provide datanames= with data= argument.")
-        if isinstance(datanames, str):
-            datanames = [datanames]
-        if len(data.shape) <= 1:
-            data = np.atleast_1d(data)[:, np.newaxis]
-        assert data.shape == (n_pos, len(datanames))
-    if datanames is not None and data is None:
-        raise ValueError("Provide data= with datanames= argument.")
-
-    m0_reshaped = np.hstack((m0, np.zeros((n_pos, 1)))).T[:, np.newaxis, :]
-    m1_reshaped = np.hstack((m1, np.zeros((n_pos, 1)))).T[:, np.newaxis, :]
-    m2_reshaped = np.hstack((m2, np.zeros((n_pos, 1)))).T[:, np.newaxis, :]
-    centers_reshaped = np.hstack((centers, np.ones((n_pos, 1)))).T[:, np.newaxis, :]
-
-    matsimnibs = np.concatenate((m0_reshaped, m1_reshaped, m2_reshaped, centers_reshaped), axis=1)
-
-    # write hdf5 file
-    if not fn_hdf.endswith('.hdf5'):
-        fn_hdf += '.hdf5'
-    if os.path.exists(fn_hdf) and not overwrite:
-        raise OSError(fn_hdf + " already exists. Set overwrite flag for create_stimsite_from_poslist.")
-
-    with h5py.File(fn_hdf, 'w') as f:
-        f.create_dataset('centers', data=centers.astype(np.float64))
-        f.create_dataset('m0', data=m0.astype(np.float64))
-        f.create_dataset('m1', data=m1.astype(np.float64))
-        f.create_dataset('m2', data=m2.astype(np.float64))
-        f.create_dataset("matsimnibs", data=matsimnibs)
-
-        if data is not None:
-            for i, col in enumerate(data.T):
-                f.create_dataset('/data/' + datanames[i], data=col)
-
-    # write .xdmf file
-    with open(fn_hdf[:-4] + 'xdmf', 'w') as f:
-        fn_hdf = os.path.basename(fn_hdf)  # relative links
-    
-        # header
-        f.write('<?xml version="1.0"?>\n')
-        f.write('<!DOCTYPE Xdmf SYSTEM "Xdmf.dtd" []>\n')
-        f.write('<Xdmf Version="2.0" xmlns:xi="http://www.w3.org/2001/XInclude">\n')
-        f.write('<Domain>\n')
-        f.write('<Grid CollectionType="Spatial" GridType="Collection" Name="Collection">\n')
-    
-        # one grid for coil dipole nodes...store data hdf5.
-        #######################################################
-        f.write('<Grid Name="stimsites" GridType="Uniform">\n')
-        f.write(f'<Topology NumberOfElements="{centers.shape[0]}" TopologyType="Polyvertex" Name="Tri">\n')
-        f.write(f'\t<DataItem Format="XML" Dimensions="{centers.shape[0]} 1">\n')
-        np.savetxt(f, list(range(centers.shape[0])), fmt='\t%d', delimiter=' ')  # 1 2 3 4 ... N_Points
-        f.write('\t</DataItem>\n')
-        f.write('</Topology>\n\n')
-    
-        # nodes
-        f.write('<Geometry GeometryType="XYZ">\n')
-        f.write(f'\t<DataItem Format="HDF" Dimensions="{centers.shape[0]} 3">\n')
-        f.write(f'\t{fn_hdf}:/centers\n')
-        f.write('\t</DataItem>\n')
-        f.write('</Geometry>\n\n')
-    
-        # data
-        # dipole magnitude
-        # the 4 vectors
-        for i in range(3):
-            f.write(f'\t\t<Attribute Name="dir_{i}" AttributeType="Vector" Center="Cell">\n')
-            f.write(f'\t\t\t<DataItem Format="HDF" Dimensions="{centers.shape[0]} 3">\n')
-            f.write(f'\t\t\t{fn_hdf}:/m{i}\n')
-            f.write('\t\t\t</DataItem>\n')
-            f.write('\t\t</Attribute>\n\n')
-    
-        if data is not None:
-            for i, col in enumerate(data.T):
-                f.write(f'\t\t<Attribute Name="{datanames[i]}" AttributeType="Scalar" Center="Cell">\n')
-                f.write('\t\t\t<DataItem Format="HDF" Dimensions="' + str(centers.shape[0]) + ' 1">\n')
-                f.write(f'\t\t\t{fn_hdf}:/data/{datanames[i]}\n')
-                f.write('\t\t\t</DataItem>\n')
-                f.write('\t\t</Attribute>\n\n')
-    
-        f.write('</Grid>\n')
-        # end coil dipole data
-    
-        # footer
-        f.write('</Grid>\n')
-        f.write('</Domain>\n')
-        f.write('</Xdmf>\n')
-
-
 def sort_opt_coil_positions(fn_coil_pos_opt, fn_coil_pos, fn_out_hdf5=None, root_path="/0/0/", verbose=False,
                             print_output=False):
     """
-    Sorts coil positions according to Traveling Salesman problem
+    Sorts coil positions according to Traveling Salesman problem.
 
     Parameters
     ----------
@@ -1185,8 +680,8 @@ def sort_opt_coil_positions(fn_coil_pos_opt, fn_coil_pos, fn_out_hdf5=None, root
                 else:
                     # Euclidean distance
                     distances[from_counter][to_counter] = (int(
-                        math.hypot((from_node[0] - to_node[0]),
-                                   (from_node[1] - to_node[1]))))
+                            math.hypot((from_node[0] - to_node[0]),
+                                       (from_node[1] - to_node[1]))))
         return distances
 
     def get_routes(s, r, m):
@@ -1293,7 +788,7 @@ def random_walk_coil(start_mat, n_steps, fn_mesh_hdf5, angles_dev=3, distance_lo
 
     Parameters
     ----------
-    start_mat : np.ndarry
+    start_mat : np.ndarray
         (4, 4) SimNIBS matsimnibs.
     n_steps : int
         Number of steps to walk.
@@ -1332,10 +827,10 @@ def random_walk_coil(start_mat, n_steps, fn_mesh_hdf5, angles_dev=3, distance_lo
         # walk angles
         for idx, axis in enumerate(['x', 'y', 'z']):
             if angles_dev[idx] != 0:
-                mat_rot = pynibs.rotate_matsimnibs_euler(axis=axis,
-                                                         angle=np.random.normal(scale=angles_dev[idx]),
-                                                         matsimnibs=mat_rot,
-                                                         metric=angles_metric)
+                mat_rot = pynibs.util.rotations.rotate_matsimnibs_euler(axis=axis,
+                                                                        angle=np.random.normal(scale=angles_dev[idx]),
+                                                                        matsimnibs=mat_rot,
+                                                                        metric=angles_metric)
             mat[:3, :3] = mat_rot[:3, :3]
         mats.append(mat)
 
@@ -1345,23 +840,198 @@ def random_walk_coil(start_mat, n_steps, fn_mesh_hdf5, angles_dev=3, distance_lo
     assert distance_low >= 0 and distance_high >= 0
     assert distance_high >= distance_low
     distances = np.random.uniform(low=distance_low, high=distance_high, size=n_steps + 1)
-    mats = pynibs.coil_distance_correction_matsimnibs(matsimnibs=mats,
-                                                      fn_mesh_hdf5=fn_mesh_hdf5,
-                                                      distance=distances)
+    mats = pynibs.expio.coil_distance_correction_matsimnibs(matsimnibs=mats,
+                                                            fn_mesh_hdf5=fn_mesh_hdf5,
+                                                            distance=distances)
 
     if coil_pos_fn is not None:
-        pynibs.write_coil_pos_hdf5(fn_hdf=os.path.splitext(coil_pos_fn)[0],
-                                   centers=mats[:3, 3, :].T,
-                                   m0=mats[:3, 0, :].T,
-                                   m1=mats[:3, 1, :].T,
-                                   m2=mats[:3, 2, :].T,
-                                   overwrite=True)
-
-        pynibs.write_coil_sequence_xdmf(coil_pos_fn,
-                                        np.arange(n_steps + 1),
-                                        vec1=mats[:3, 0, :].T,
-                                        vec2=mats[:3, 1, :].T,
-                                        vec3=mats[:3, 2, :].T,
-                                        output_xdmf=f"{os.path.splitext(coil_pos_fn)[0]}.xdmf")
+        pynibs.coil.write_coil_pos_hdf5(fn_hdf=os.path.splitext(coil_pos_fn)[0],
+                                        centers=mats[:3, 3, :].T,
+                                        m0=mats[:3, 0, :].T,
+                                        m1=mats[:3, 1, :].T,
+                                        m2=mats[:3, 2, :].T,
+                                        overwrite=True)
+
+        pynibs.coil.write_coil_sequence_xdmf(coil_pos_fn,
+                                             np.arange(n_steps + 1),
+                                             vec1=mats[:3, 0, :].T,
+                                             vec2=mats[:3, 1, :].T,
+                                             vec3=mats[:3, 2, :].T,
+                                             output_xdmf=f"{os.path.splitext(coil_pos_fn)[0]}.xdmf")
 
     return mats
+
+
+def shift_coil_to_skin(mesh, coil, matsimnibs, dist=1, dist_neigh=50, coil_elm_idx=None, verbose=False):
+    """
+    Shifts the coil position to the skin surface, also works for bent coil models.
+
+    Parameters
+    ----------
+    mesh : simnibs.mesh_io.Mesh or str
+        SimNIBS .msh.
+    coil : simnibs.simulation.tms_coil.tms_coil.TmsCoil or str
+        .tcd coil model.
+    matsimnibs : np.ndarray
+        (4, 4) SimNIBS matsimnibs coil position / orientation.
+    dist : float, default: 0
+        Target (minimum) coil-skin distance.
+    dist_neigh : float, default: 50
+        If set, only mesh nodes with a distance < dist_neigh are considered for
+         the distance calculation to speed up computation.
+    coil_elm_idx : list of int, optional
+        Which coil elements to use.
+    verbose : bool, default: False
+        Print output messages.
+
+    Returns
+    -------
+    matsimnibs_shifted : np.ndarray
+        (4, 4) Shifted coil position / orientation.
+    min_dist : float
+        (Minimum) coil-skin distance before shifting.
+    """
+    import trimesh
+    import simnibs
+    if isinstance(mesh, str):
+        mesh = simnibs.mesh_io.read_msh(mesh)
+        mesh = mesh.crop_mesh(1005)
+
+    if isinstance(coil, str):
+        from simnibs.simulation.tms_coil.tms_coil import TmsCoil
+        coil = TmsCoil.from_file(coil)
+
+    if verbose:
+        pynibs.matsim2paraview(matsimnibs)
+
+    casing = coil.get_mesh(
+            coil_affine=matsimnibs,
+            include_optimization_points=False,
+            include_coil_elements=False,
+    )
+    if coil_elm_idx is not None:
+        mesh_case = trimesh.Trimesh(vertices=casing.nodes.node_coord,
+                                    faces=casing.elm.node_number_list[coil_elm_idx, :3] - 1)
+        casing = casing.nodes.node_coord[casing.elm.node_number_list - 1][coil_elm_idx, :3, :]
+    else:
+        mesh_case = trimesh.Trimesh(vertices=casing.nodes.node_coord, faces=casing.elm.node_number_list[:, :3] - 1)
+        casing = casing.nodes.node_coord[casing.elm.node_number_list - 1][:, :3, :]
+
+    if dist_neigh is not None:
+        close_mesh_nodes = []
+        for mesh_node_i, mesh_node in tqdm.tqdm(enumerate(mesh.nodes.node_coord),
+                                                leave=False, total=mesh.nodes.node_coord.shape[0],
+                                                desc=f"Finding close mesh nodes to coil {casing.shape[0]}"):
+            if mesh_node_i % 10 != 0:
+                # speed this up by subsampling
+                continue
+            closest = pynibs.util.rotations.points_to_triangles(mesh_node[np.newaxis, :], casing)
+
+            # if (np.linalg.norm(mesh_node - coil_nodes, axis=1) < dist_neigh).any():
+            if (np.linalg.norm(mesh_node - closest[0, ::], axis=1) < dist_neigh).any():
+                close_mesh_nodes.append(mesh_node_i + 1)
+        if verbose:
+            print(f"{len(close_mesh_nodes)} close mesh nodes found.")
+
+        mesh = mesh.crop_mesh(nodes=close_mesh_nodes)
+
+    ray_directions = np.repeat(matsimnibs[:3, 2][np.newaxis, :], mesh.nodes.node_coord.shape[0], axis=0)
+    loc, index_ray, index_tri = mesh_case.ray.intersects_location(ray_origins=mesh.nodes.node_coord,
+                                                                  ray_directions=-ray_directions)
+
+    min_dist = np.linalg.norm(loc - mesh.nodes.node_coord[index_ray], axis=1).min()
+    if verbose:
+        print(f"Minimum distance to cortex surface: {min_dist} mm")
+
+    assert min_dist > 0, f"Coil touches head: {min_dist}"
+
+    # apply the target distance
+    min_dist -= dist
+
+    # shift coil placement in the z-coil axis direction towards the head
+    add = min_dist * matsimnibs[:3, 2]
+    # print(f"vec: {np.round(matsimnibs[:3, 2], 2)}:  by {np.round(add,2)} mm. Mindist: {np.round(min_dist,2)}")
+    matsimnibs[:3, 3] += add
+
+    return matsimnibs, min_dist
+
+
+def shift_many_coil_placements(mesh, coil, matsimnibs, dist=1, dist_neigh=50, flat_coil=False,
+                               z_cut_off=None, verbose=False):
+    """
+    Shifts many coil placements to the cortex surface.
+
+    Parameters
+    ----------
+    mesh : simnibs.mesh_io.Mesh or str
+        SimNIBD .msh.
+    coil : simnibs.simulation.tms_coil.tms_coil.TmsCoil or str
+        .tcd coil model.
+    matsimnibs : np.ndarray
+        (4, 4, N) SimNIBS matsimnibs coil position / orientation.
+    dist : float, default: 0
+        Target (minimum) coil-skin distance.
+    dist_neigh : float, default: 50
+        If set, only mesh nodes with a distance < dist_neigh are considered for
+         the distance calculation to speed up computation.
+    flat_coil : bool, default: False
+        If True, the coil is assumed to be flat and shifts for the same position are applied across all rotations.
+    z_cut_off : float, optional
+        Cut coil case at this z-offset to speed up computation
+    verbose : bool, default: False
+        Print output messages.
+
+    Returns
+    -------
+    matsimnibs : np.ndarray
+        (4, 4, N) Shifted coil positions / orientations.
+    """
+    import simnibs
+    if isinstance(mesh, str):
+        mesh = simnibs.mesh_io.read_msh(mesh)
+    mesh = mesh.crop_mesh(1005)
+    if isinstance(coil, str):
+        from simnibs.simulation.tms_coil.tms_coil import TmsCoil
+        coil = TmsCoil.from_file(coil)
+
+    if isinstance(matsimnibs, str):
+        with h5py.File(matsimnibs, 'r') as f:
+            matsimnibs = f['matsimnibs'][:]
+
+    shifts = np.zeros((3, matsimnibs.shape[2]))
+
+    # just look at bottom side of coil to speed up things
+    if z_cut_off is not None:
+        casing = coil.get_mesh(
+                coil_affine=None,
+                include_optimization_points=False,
+                include_coil_elements=False,
+        )
+        casing = casing.nodes.node_coord[casing.elm.node_number_list - 1][:, :3, :]
+        bottom_coil_idx = np.squeeze(np.argwhere(np.sum(casing[:, :, 2] > z_cut_off, axis=1) > 1))
+        assert bottom_coil_idx.shape[0] > 0, "No coil elements found above z_cut_off"
+    else:
+        bottom_coil_idx = None
+
+    # perform shift_coil_to_cortex for each matsimnibs
+    for idx in tqdm.tqdm(range(matsimnibs.shape[2]), position=1, desc="Shift coils"):
+        if (shifts[:, idx] != 0).any():
+            # let's skip the ones we already know
+            continue
+        matsim = matsimnibs[:, :, idx].copy()
+
+        # get shifted coil placement for this idx
+        matsim_shifted, _ = shift_coil_to_skin(mesh, coil, matsim, dist=dist, dist_neigh=dist_neigh,
+                                               coil_elm_idx=bottom_coil_idx, verbose=verbose)
+
+        if flat_coil:
+            # let's see if there are other coil placements with the same position
+            same_pos_idx = \
+                np.where(np.sum(matsimnibs[:3, 3, :] == matsimnibs[:3, 3, idx][:, np.newaxis], axis=0) == 3)[0]
+        else:
+            same_pos_idx = np.array([idx])
+        shifts[:, same_pos_idx] = matsim_shifted[:3, 3][:, np.newaxis]
+
+    matsimnibs[:3, 3, :] = shifts
+
+    return matsimnibs