magba 0.6.0

Magnetic computation library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

/*
 * Magba is licensed under The 3-Clause BSD, see LICENSE.
 * Copyright 2025 Sira Pornsiriprasert <code@psira.me>
 */

//! Analytical computation of magnetic fields for various source geometries.
//!
//! # Argument Conventions
//!
//! The arguments in the field computation functions follow the order of
//! observer position(s), magnet position, magnet orientation, and the other
//! arguments needed for the specific geometry. For the batch functions, the
//! last argument is a slice for receiving the output. This is to avoid
//! allocations and enable use in `no-alloc` contexts.
//!
//! # Batch and Non-Batch Functions
//!
//! The field computation functions are available in three variants:
//!
//! - **Non-batch functions** (e.g., [cuboid_B], [dipole_B]):
//!   Compute the magnetic field at a single observation point.
//! - **Batch functions** (e.g., [cuboid_B_batch], [dipole_B_batch]):
//!   Compute the magnetic field at multiple observation points simultaneously.
//! - **Sum multiple functions** (e.g., [sum_multiple_cuboid_B], [sum_multiple_dipole_B]):
//!   Compute the magnetic field at a single observation point by summing the
//!   fields of multiple magnets.
//!
//! ## Parallelization
//!
//! Batch and sum multiple functions are parallelized if the `rayon` feature is
//! enabled (default). If the `rayon` feature is disabled, the batch functions
//! will process the points serially on a single thread.
//!
//! To automatically tune the threshold for your computation environment,
//!
//! 1. Download the source code locally
//! 2. Run `cargo bench threshold --features unstable`.
//! 3. Run `cargo run --package magba --example generate_threshold_code`.
//! 4. Copy the generated code from `benches/impl_parallel.txt` to the function *_B_batch,
//!    such as `fields::field_cuboid::cuboid_B_batch`.
//! 5. Recompile and install Magba with the adjusted threshold locally.
//!
//! # Examples
//!
//! ```
//! # use magba::fields::*;
//! # use magba::prelude::*;
//! # use nalgebra::{point, vector, UnitQuaternion};
//! let field = cuboid_B(
//!     point![0.0, 0.0, 0.0],      // Observer position (m)
//!     point![0.0, 0.0, 0.0],      // Magnet position (m)
//!     UnitQuaternion::identity(), // Magnet orientation as unit quaternion
//!     vector![0.0, 0.0, 1.0],     // Magnet polarization (T)
//!     vector![0.01, 0.01, 0.02],  // Magnet dimensions (m)
//! );
//! ```
//!
//! # Internal Functions (`unstable`)
//!
//! The following functions with `unstable` badges are internal
//! functions. They are subject to change without prior notice.
//! However, you can access them via the `unstable` feature flag:
//!
//! ```bash
//! cargo add magba --features unstable
//! ```

mod field_circular;
mod field_cuboid;
mod field_cylinder;
mod field_dipole;
#[cfg(feature = "alloc")]
mod field_path_current;
#[cfg(feature = "mesh")]
mod field_sheet_current;
mod field_sphere;
mod field_tetrahedron;
mod field_triangle;
mod field_triangle_current;

pub use field_circular::{circular_B, circular_B_batch, sum_multiple_circular_B};
pub use field_cuboid::{cuboid_B, cuboid_B_batch, sum_multiple_cuboid_B};
pub use field_cylinder::{cylinder_B, cylinder_B_batch, sum_multiple_cylinder_B};
pub use field_dipole::{dipole_B, dipole_B_batch, sum_multiple_dipole_B};
#[cfg(feature = "alloc")]
pub use field_path_current::{path_current_B, path_current_B_batch, sum_multiple_path_current_B};
#[cfg(feature = "mesh")]
pub use field_sheet_current::{
    sheet_current_B, sheet_current_B_batch, sum_multiple_sheet_current_B,
};
pub use field_sphere::{sphere_B, sphere_B_batch, sum_multiple_sphere_B};
pub use field_tetrahedron::{sum_multiple_tetrahedron_B, tetrahedron_B, tetrahedron_B_batch};
pub use field_triangle::{sum_multiple_triangle_B, triangle_B, triangle_B_batch};
pub use field_triangle_current::{
    sum_multiple_triangle_current_B, triangle_current_B, triangle_current_B_batch,
};

#[cfg(feature = "mesh")]
mod field_mesh;
#[cfg(feature = "mesh")]
pub use field_mesh::{mesh_B, mesh_B_batch, sum_multiple_mesh_B};

crate::crate_utils::need_unstable! {
    pub use field_cuboid::local_cuboid_B;
    pub use field_cylinder::{
        cylinder_B_cyl, local_cylinder_B, unit_axial_cylinder_B_cyl, unit_diametric_cylinder_B_cyl,
    };
    pub use field_dipole::local_dipole_B;
    pub use field_sphere::local_sphere_B;
    pub use field_tetrahedron::{local_tetrahedron_B, tetrahedron_B_precomputed, precompute_tetrahedron};
    pub use field_triangle::local_triangle_B;

    #[cfg(feature = "mesh")]
    pub use field_mesh::local_mesh_B;

    #[cfg(feature = "alloc")]
    pub use field_path_current::local_path_current_B;
    pub use field_triangle_current::local_triangle_current_B;
    #[cfg(feature = "mesh")]
    pub use field_sheet_current::local_sheet_current_B;
}