From 8840efe727d401886cefbc59dd655d3c80b31727 Mon Sep 17 00:00:00 2001 From: Mario Date: Mon, 10 Apr 2017 15:36:27 +0200 Subject: [PATCH] readme and license changes; small correction in loop_3d In preparation for repository publication --- +magnetic_field/loop_3d.m | 4 +- LICENSE.md | 22 ++++++++- README.md | 94 ++++++++++++++++++++++++++++----------- 3 files changed, 91 insertions(+), 29 deletions(-) diff --git a/+magnetic_field/loop_3d.m b/+magnetic_field/loop_3d.m index 63ba44e..9b3e5e0 100644 --- a/+magnetic_field/loop_3d.m +++ b/+magnetic_field/loop_3d.m @@ -118,8 +118,8 @@ function set_B0(h,B0) points(~good,:) = 0; % calculate 2d derivatives and BR field (in local axes) [dBZ_dZ,dBZ_dR,dBR_dZ,dBR_dR] = h.derivatives_2d(Z,R); - [~,~,BR] = h.field_2d(Z,R); - BR_R(good) = BR(good)./R(good); + [~,~,BR_R] = h.field_2d(Z,R); + BR_R(good) = BR_R(good)./R(good); BR_R(~good) = dBR_dR(~good); % Transform into global axes derivatives of the field. Zx1 = h.axis(1); % escalar product 1Z*1x. These are the projections of Z and R versors along X,Y,Z. diff --git a/LICENSE.md b/LICENSE.md index a35233c..08577d6 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1 +1,21 @@ -Copyright (c) 2017 Mario Merino. All rights reserved \ No newline at end of file +MIT License + +Copyright (c) 2017 Mario Merino + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index 451079a..17015a1 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,89 @@ MAGNETIC_FIELD ============== -Magnetic field computations based on the analytical solution for coils and +Magnetic field classes based on the analytical solution for coils and wire segments, in 2D and 3D. +## Installation + +Installation requires simply that you +[download FUMAGNO](https://github.com/mariomerinomartinez/fumagno/archive/master.zip) +and add the base directory (the one that contains the `+fumagno` directory) to +your Matlab path. + +### Dependencies + +A recent version of Matlab is needed to run the code. +The code has been developed in Matlab 2016a Academic version. + +MAGNETIC_FIELD +depends on other Matlab packages that you can download from my GitHub +account: +[utilities](https://github.com/mariomerinomartinez/utilities) +and +[constants_and_units](https://github.com/mariomerinomartinez/constants_and_units). +These packages must be installed and added to your Matlab path beforehand. + +## Usage + The code is structured into several Matlab classes as follows: -- element, element_2d, element_3d (abstract classes): all magnetic field +* `element`, `element_2d`, `element_3d` (abstract classes): all magnetic field generator elements inherit from these parent classes. Used to set some standard interfaces; not intended for direct usage by user. They also provide some commodity functions to calculate the field on a plane and to plot a field component on a plane. +* `loop_2d`, `loop_3d`: analytical magnetic field of a single current loop of +zero thickness, after solving the singularity for Br at the axis. The 2d +version defines the magnetic streamfunction psi. The most thoroughly tested +classes. +* `library_2d`, `library_3d`: allow to define some interpolation libraries for +the fields and interpolate there. +* `path_3d`: the magnetic field of a wire defined by a set of nodes, computed +in a step-wise manner with Biot-Savart's Law. Not extensively tested yet; +could contain errors. +* `wire_2d`, `wire_3d`: the analytic magnetic field of a straight infinite +conductor. Not extensively tested yet; could contain errors. +* `uniform_2d`, `uniform_3d`: a constant, uniform magnetic field in a given +direction. +* `array` (abstract class): sets the basic interfaces for arrays of generators +(i.e. collections of generator elements). +* `array_2d`, `array_3d`: these are classes that allow collecting many +generator elements in an array, and redefine some methods to compute field of +all elements simultaneously. -* loop_2d, loop_3d: analytical magnetic field of a single current loop of zero -thickness, after solving the singularity for Br at the axis. The 2d version -defines the magnetic streamfunction psi. Inherit from element_2d and -element_3d, respectively. Loop_3d, in addition, inherits from loop_2d. +Usage is straight forward. Start by creating an object of the desired class and setting its parameters, then call one of its methods: -* library_2d, library_3d: allows to define some interpolation libraries for -the fields and interpolate there. Inherit from element_2d and element_3d, -respectively. +```Matlab +mf = magnetic_field.loop_2d('RL',5,'I',10); % Create loop_2d object +[psi,Bz,Br] = mf.field_2d(0,0); % query the field at z=0, r=0 +``` -* path_3d: the magnetic field of a wire defined by a set of nodes. Inherits -from element_3d. +### Testing -* uniform_2d, uniform_3d: a constant, uniform magnetic field in a given -direction. Inherit from element_2d and element_3d, respectively. +Unit tests are found in the `/test` subdirectory. After adding the package to +your Matlab path, you can run all tests by executing `runtests` from this +subdirectory. -* array (abstract class): sets the basic interfaces for arrays of generators -(i.e. collections of generator elements). Inherits from element. +## Contributing -* array_2d, array_3d: these and 3d are classes that collect many generator -elements in an array, and redefine some methods to compute field of all -elements simultaneously. Inherit from array. +If you have any comments for improvement or +are interested in contributing to the continued +development of this or any of my other codes, you can contact me +through my [personal website](http://mariomerino.uc3m.es/). -Testing -------- +## Acknowledging -Unit tests are found in the /test subdirectory. After adding the package to -your Matlab path, you can run all tests by executing 'runtests' from this -subdirectory. +This program is released as open source in the hope that it will be useful to +other people. + +If you find it useful and/or use it in any of your works, I kindly ask you +to acknowledge it by citing [TBD] (preferred) +and/or by citing the code directly as: [TBD] + +## License -License -------- +Copyright (c) 2017 Mario Merino. The software is released as open +source with the [MIT License](LICENSE.md). -Copyright (c) 2017 Mario Merino. All rights reserved + \ No newline at end of file