fastcap2 package

Module contents

class fastcap2.Problem(*args: Any, **kwargs: Any)

Bases: Problem

Describes a FastCap2 project (aka ‘problem’)

Parameters:

title – The optional title string. It is used as the default title for surfaces.

Use this class following these steps:

import fastcap2 as fc2

problem = fc2.Problem(title = "A sample problem")

# loads a problem from a FastCap2 list file
problem.load_list("geometry.lst")

# solves the problem and returns the cap matrix in MKS units
cap_matrix = problem.solve()
print(cap_matrix)

# dumps the geometry to a PS file
problem.dump_ps("geo.ps")

Dumping the geometry to a PS file comes very handy when debugging the geometry setup.

Once solve() or dump_ps() is called, the geometry of the problem should not be modified again. Currently this will put the object in an undefined state.

BOTH = 3

Specifies ‘dielectric interaface with very thin conductor on it’ kind for the surface (see add())

CONDTR = 0

Specifies ‘conductor’ kind for the surface (see add())

DIELEC = 1

Specifies ‘dielectric interface’ kind for the surface (see add())

XI = 0

Specifies ‘x axis’ for ps_upaxis()

YI = 1

Specifies ‘y axis’ for ps_upaxis()

ZI = 2

Specifies ‘z axis’ for ps_upaxis()

add(surface: fastcap2.Surface, link: bool = False, group: str | None = None, kind: int = 0, ref_point_inside: bool = True, outside_perm: float = 1.0, inside_perm: float = 1.0, d: Tuple[float, float, float] = (0.0, 0.0, 0.0), r: Tuple[float, float, float] = (0.0, 0.0, 0.0), flipx: bool = False, flipy: bool = False, flipz: bool = False, rotx: float = 0.0, roty: float = 0.0, rotz: float = 0.0, scale: float = 1.0, scalex: float = 1.0, scaley: float = 1.0, scalez: float = 1.0)

Adds a surface object to the problem

Parameters:

  • surface – The surface to add.

  • group – See load() for details.

  • link – See load() for details.

  • kind – The type of the surface (conductor or dielectric or dielectric interface). See load() for details.

  • outside_perm – The permittivity outside of the surface. See load() for details.

  • inside_perm – The permittivity inside of the surface (only for dielectric surfaces). See load() for details.

  • d – Translates the surface. See load() for details.

  • r – The reference point for surface normalisation. Needed for dielectric surfaces. See load() for details.

  • ref_point_inside – True, if the reference point is inside the surface. Needed for dielectric surfaces. See load() for details.

  • flipx – Flips the surface at the yz plane. See load() for details.

  • flipy – Flips the surface at the xz plane. See load() for details.

  • flipz – Flips the surface at the xy plane. See load() for details.

  • rotx – Rotates the surface around the x axis by the given angle. See load() for details.

  • roty – Rotates the surface around the y axis by the given angle. See load() for details.

  • rotz – Rotates the surface around the z axis by the given angle. See load() for details.

  • scale – Scales the surface by the given factor. See load() for details.

  • scalex – Scales the surface by the given factor in x direction. See load() for details.

  • scaley – Scales the surface by the given factor in y direction. See load() for details.

  • scalez – Scales the surface by the given factor in z direction. See load() for details.

A surface can be added multiple times with different transformation parameters, so it is easy to form structures with multiple conductors.

The other parameters are explained in the description of the load() function.

conductors() → list[str]

Returns the effective list of conductors present in the capacitance matrix

The list corresponds to the rows and columns of the capacitance matrix.

Note: The list of conductors is only available after a call to solve() or dump_ps().

dump_ps(filename)

Produces a PS file with the geometries

See the manifold ps_… options that configure PS output.

Note: calling this function continuously allocates memory until the Problem object is released.

property expansion_order: int

The multipole expansion order

This property corresponds to option “-o” of the original “fastcap” program.

A value of 0 indicates automatic expansion.

extent() → list[list[float], list[float]]

Gets the extent of all geometries of all surfaces (bounding box)

The first tuple is the minimum x, y and z, the second one the maximum x, y and z.

property iter_tol: float

The iteration tolerance

This property corresponds to option “-i” of the original “fastcap” program.

The default value is 0.01.

load(file: str, link: bool = False, group: str | None = None, kind: int = 0, ref_point_inside: bool = True, outside_perm: float = 1.0, inside_perm: float = 1.0, d: Tuple[float, float, float] = (0.0, 0.0, 0.0), r: Tuple[float, float, float] = (0.0, 0.0, 0.0), flipx: bool = False, flipy: bool = False, flipz: bool = False, rotx: float = 0.0, roty: float = 0.0, rotz: float = 0.0, scale: float = 1.0, scalex: float = 1.0, scaley: float = 1.0, scalez: float = 1.0)

Loads a single “quickif”-style geometry file

Parameters:

  • file – The file to load

  • link – If True, links this surface to the previous conductor.

  • group – The name of the conductor group to form.

  • kind – The type of the surface (conductor or dielectric or dielectric interface).

  • outside_perm – The permittivity outside of the surface.

  • inside_perm – The permittivity inside of the surface (only for dielectric surfaces).

  • d – Translates the surface.

  • r – The reference point for surface normalisation. Needed for dielectric surfaces.

  • ref_point_inside – True, if the reference point is inside the surface. Needed for dielectric surfaces.

  • flipx – Flips the surface at the yz plane.

  • flipy – Flips the surface at the xz plane.

  • flipz – Flips the surface at the xy plane.

  • rotx – Rotates the surface around the x axis by the given angle.

  • roty – Rotates the surface around the y axis by the given angle.

  • rotz – Rotates the surface around the z axis by the given angle.

  • scale – Scales the surface by the given factor.

  • scalex – Scales the surface by the given factor in x direction.

  • scaley – Scales the surface by the given factor in y direction.

  • scalez – Scales the surface by the given factor in z direction.

Note that the files are not loaded immediately, but upon solve().

By design of the file format, only conductor surfaces can be loaded by this method.

The group name together with the conductor name inside the file will form an effective conductor name of the form name%group. All surfaces with the same effective conductor name become connected. So it is possible to form a connected surface from multiple files or multiple calls of the same file by giving them the same group name.

link is a similar mechanism than group, but will automatically use the group of the surface loaded previously if set to True.

link and group are mutually exclusive.

kind specifies which type of surface is given. The surface can be:

outside_perm specifies the permittivity outside of the conductor or dielectric surface. inside_perm specifies the permittivity inside the surface for DIELEC or BOTH type.

In order to tell inside from outside halfspace and to properly orient the faces, a reference point needs to be given that does not lie on the surface. This is mandatory for types DIELEC and BOTH. For CONDTR type, this specification is not required - “outside” refers to both sides of the surface. Specify the reference point with the r parameter which is a triple of x, y and z values.

By default, the reference point is taken to be inside the surface. By using ref_point_inside = False, the reference point is taken to be outside the surface.

Additional transformations can be applied to the surface before using it:

  • A displacement (translation) - d parameter

  • Rotation around different axes - rotx, roty and rotz parameters

  • Mirroring in x, y or z direction - flipx, flipy and flipz parameters

  • Scaling (isotropic or single direction) - scale, scalex, scaley and scalez parameters

The order in which the transformations are applied is:

  • Scaling by scale, scalex, scaley and scalez

  • Flipping by flipx, flipy and flipz

  • Rotation by rotx

  • Rotation by roty

  • Rotation by rotz

  • Translation by d

load_list(file: str)

Loads a “list-style” geometry file

This method corresponds to option “-l” in the original “fastcap” program.

property partitioning_depth: int

The partitioning depth

This property corresponds to option “-d” of the original “fastcap” program.

A negative value indicates automatic depth mode. In automatic mode, solve() will set the depth actually used.

property perm_factor: float

The permittivity factor

All dielectric permittivities will be multiplied by this factor. The default value is 1.0.

This property corresponds to option “-p” of the original “fastcap” program.

property ps_axislength: float

PS output: the axis length

This property corresponds to option “-x” of the original “fastcap” program.

property ps_azimuth: float

PS output: the azimuth angle

This property corresponds to option “-a” of the original “fastcap” program.

property ps_distance: float

PS output: the distance

This property corresponds to option “-h” of the original “fastcap” program.

property ps_elevation: float

PS output: the elevation angle

This property corresponds to option “-e” of the original “fastcap” program.

property ps_linewidth: float

PS output: the line width

This property corresponds to option “-w” of the original “fastcap” program.

property ps_no_dielectric: bool

PS output: remove DIELEC type surfaces from all .ps picture files

This property corresponds to option “-rd” of the original “fastcap” program.

property ps_no_showpage: bool

PS output: suppress showpage in all .ps picture files

This property corresponds to option “-v” of the original “fastcap” program.

property ps_number_faces: bool

PS output: number faces with input order numbers

This property corresponds to option “-n” of the original “fastcap” program.

property ps_rotation: float

PS output: the rotation angle

This property corresponds to option “-r” of the original “fastcap” program.

property ps_scale: float

PS output: the scale

This property corresponds to option “-s” of the original “fastcap” program.

property ps_show_hidden: bool

PS output: do not remove hidden faces

This property corresponds to option “-f” of the original “fastcap” program.

property ps_upaxis: int

PS output: specifies the “up” axis

This property corresponds to option “-u” of the original “fastcap” program.

Values are: * Problem.XI for x axis * Problem.YI for y axis * Problem.ZI for z axis

property qps_file_base: str | None

PS output: select file base for at-1V charge distribution .ps pictures

If this property is set, charge distribution .ps pictures will be generated during the solve() call. For each conductor a different .ps file will be written. The .ps files are named using the value of this property and appending the conductor number and a .ps suffix.

For example, setting this property to /tmp/charges will generate .ps files called /tmp/charges1.ps, /tmp/charges2.ps and so on.

Setting this property to None (the default) will disable generating the charge distribution pictures.

The charge distribution output can be configured further using the qps_select_q(), qps_remove_q(), qps_no_key() and qps_total_charges() properties.

Note, that charge distribution pictures are only generated during solve(), but not by dump_ps().

property qps_no_key: bool

PS output: remove key from all charge distribution .ps pictures

This property corresponds to option “-rk” of the original “fastcap” program.

This option is effective only if charge distribution pictures are enabled by setting the qps_file_base() property.

property qps_remove_q: list[str] | None

PS output: remove conductors from all charge distribution .ps pictures

The argument is a list of group-qualified conductor names in the form name%group, e.g. PLATE%GROUP1. Conductors will be identified by matching the leading part - e.g. PLATE%GROUP will match conductors PLATE%GROUP1, PLATE%GROUP2 etc.

This property corresponds to option “-rc” of the original “fastcap” program. A value of ‘None’ for this property will enable all conductors in the charge distribution picture.

This option is effective only if charge distribution pictures are enabled by setting the qps_file_base() property.

property qps_select_q: list[str] | None

PS output: select conductors for charge distribution .ps pictures

The argument is a list of group-qualified conductor names in the form name%group, e.g. PLATE%GROUP1. Conductors will be identified by matching the leading part - e.g. PLATE%GROUP will match conductors PLATE%GROUP1, PLATE%GROUP2 etc.

This property corresponds to option “-q” of the original “fastcap” program. A value of ‘None’ for this property will select all conductors.

This option is effective only if charge distribution pictures are enabled by setting the qps_file_base() property.

property qps_total_charges: bool

PS output: display total charges in charge distribution .ps pictures

This property corresponds to option “-dc” of the original “fastcap” program.

This option is effective only if charge distribution pictures are enabled by setting the qps_file_base() property.

property remove_conductors: list[str] | None

Removes the given conductors from the input

The argument is a list of group-qualified conductor names in the form name%group, e.g. PLATE%GROUP1. Conductors will be identified by matching the leading part - e.g. PLATE%GROUP will match conductors PLATE%GROUP1, PLATE%GROUP2 etc.

This property corresponds to option “-ri” of the original “fastcap” program.

The conductors with the given names will not be considered at all and will not be present in the capacitance matrix. A value of ‘None’ for this property will enable all conductors.

property skip_conductors: list[str] | None

Skips the given conductors from the solve list

The argument is a list of group-qualified conductor names in the form name%group, e.g. PLATE%GROUP1. Conductors will be identified by matching the leading part - e.g. PLATE%GROUP will match conductors PLATE%GROUP1, PLATE%GROUP2 etc.

This property corresponds to option “-rs” of the original “fastcap” program.

A value of ‘None’ for this property will select all conductors.

The effect of this option is to skip the specified conductors from the evaluation. Skipping conductors can speed up the computation as self-capacitances of these conductors and capacitances between skipped conductors are not considered.

solve() → list[list[float]]

Solves the problem and returns the capacitance matrix

Raises an exception if an error occurs.

The rows and columns correspond to the conductors returned by the conductors() method.

If elements are not computed because the corresponding rows and columns have been dropped from the input, a zero capacitance value is written there.

property title: str

The title string

The title string is an arbitrary optional string. Surfaces will see this title unless they specify their own one.

property verbose: bool

If true, the solve methods will print information about the problem and the solution

class fastcap2.Surface(*args: Any, **kwargs: Any)

Bases: Surface

Describes a FastCap2 surface

Parameters:

  • name – The conductor name for conductor-type surfaces.

  • title – The optional title string.

This object can be used instead of geometry files to specify conductor or dielectric surfaces. Create this object and use it with fastcap2.Problem.add() to specify the geometry of the problem to solve.

Details of the surface such as the kind of surface etc. are specified upon fastcap2.Problem.add().

name is a conductor identifier - surfaces with the same name/group combination are considered connected. The name is mandatory for conductor-type surfaces. The group name can be assigned when adding the surface to the Problem object.

import fastcap2 as fc2

# prepares a Surface object

surface = fc2.Surface()
surface.name = "S"
surface.add_meshed_quad((0, 0, 0), (1, 0, 0), (0, 1, 0), edge_width = 0.01, num = 10)

# prepares a problem using the meshed quad two times for cap plates 

problem = fc2.Problem(title = "A sample problem")

# lower plate: shifted down
problem.add(surface, d = (0, 0, -0.1))
# lower plate: shifted up
problem.add(surface, d = (0, 0, 0.1))

# solves the problem and returns the cap matrix in MKS units
cap_matrix = problem.solve()
print(cap_matrix)
add_meshed_quad(p0: Tuple[float, float, float], p1: Tuple[float, float, float], p2: Tuple[float, float, float], max_dim: float | None = None, num: float | None = None, edge_width: float | None = None, edge_fraction: float | None = None)

Generates a meshed quad (actually a diamond or rectangle)

Parameters:

  • p0 – the first corner.

  • p1 – the left-side adjacent corner.

  • p2 – the right-side adjacent corner.

  • max_dim – the maximum dimension of the mesh tiles.

  • num – the number of mesh tiles per shorter side.

  • edge_width – the width of the edge.

  • edge_fraction – the width of the edge as a fraction of the shorter side.

The diamond or rectangle is defined by three vectors defining a point (p0) and the adjacent other points (p1 and p2). The forth point is implicitly given by

p3 = p0 + (p1 - p0) + (p2 - p0)

The mesh generation supports a number of features:

  • The mesh size can be determined by number of maximum element dimension. If a number is given (num) the shorter side of the diamond is divided by this number to determine the mesh size. If a maximum dimension is given (max_dim), the number of tiles is determined such that the size is less than this dimension.

  • The edge of the figure can be resolved in smaller tiles rendering a thinner and more densely meshed corner. The width of the edge can either be given as a fraction of the shorter side (edge_fraction) or directly (edge_width). Note that the edge width is implemented as subtracting the corresponding lengths from the sides, so for slanted figures the edge width is not corresponding to the width of the edge mesh tiles.

The edge does not contribute in the mesh dimensioning. If neither (edge_fraction) nor (edge_width) is present, no edge is generated.

add_quad(p1: Tuple[float, float, float], p2: Tuple[float, float, float], p3: Tuple[float, float, float], p4: Tuple[float, float, float])

Adds a quad to the surface

add_tri(p1: Tuple[float, float, float], p2: Tuple[float, float, float], p3: Tuple[float, float, float])

Adds a triangle to the surface

property name: str

The name string

The name string specifies the conductor the surface belongs to. A conductor-type surface needs to have a name. Together with the group name (see fastcap2.Problem.add()), the conductor name formes an identifier. All surfaces with the same conductor identifier are considered connected.

The name must not contain ‘%’ or ‘,’ characters.

property title: str

The title string

The title string is an arbitrary optional string. Surfaces will see this title or the project title (see fastcap2.Problem.title()) if no title is given for the surface.