# Introduction¶

basicsusms is a package for computing structural sums and the effective conductivity of random composites.

The package forms a set of tools that can be divided into following submodules (see Fig. 1) presented in a bottom-up order. For theoretical details refer to Theory overview.

• basicsums.weierstrass – incorporates Weierstrass class modeling Weierstrass $$\wp$$ elliptic function and its derivative $$\wp'$$ being foundation for Eisenstein functions $$E_k$$ ($$k=2,3,\ldots$$). Instances are created based on given haflperiods of considered cell. Can be used as a standalone unit for calculations of $$\wp(z)$$ and $$\wp'(z)$$.
• basicsums.eisenstein – module for deriving mathematical objects being foundation of structural sums, i.e. Eisenstein-Rayleigh lattice sums $$S_k$$ ($$k=2,3,\ldots$$) and Eisenstein functions $$E_k$$ ($$k=2,3,\ldots$$) being algebraic combinations of $$\wp(z)$$ and $$\wp'(z)$$. Can be used as a standalone module for performing calculations of $$S_k$$ and $$E_k(z)$$. The module requires basicsums.weierstrass and is suitable for both numeric and symbolic calculations.
• basicsums.basic_sums – the key component of the basicsums package, providing high level interface for computing structural sums. The unit cell is modelled by Cell class, of which instance determines and stores corresponding lattice sums and Eisenstein functions. For a particular cell, we can consider different configurations of points or disks. In order to compute structural sums for a given configuration, we create an instance of BasicSums. At the time of creation, all required values of Eisenstein functions are computed and stored in form of matrices, before any sum is called (for more details, see [3] )
• basicsums.multi_indexes – module incorporating procedures for computing symbolic structure of consecutive multi-indexes of structural sums. The set of all structural sums is infinite, hence in applications we need its finite approximations. Functions implemented in the module, return a set of multi-indexes of structural sums that are sufficient to achieve a given polynomial approximation of the effective conductivity or a certain approximation of the structural sums feature vector.
• basicsums.conductivity – designed for an original application of basic sums: computing both purely symbolic and symbolic-numeric formulae for the effective conductivity of random 2D composites with circular non-overlapping inclusions.
• basicsums.preparation – providing functions that help the user to prepare data for the application of structural sums.
• basicsums.show_disks – this one-function module allows visualization of a system of disks in a given two-periodic cell with the help of matplotlib.

The package also incorporates a set of sample data that can be used alongside with tutorial from documentation.

## Applications¶

Let us briefly present some applications of basic sums:

• description of random changes of microstructures [4]
• geometric features of data represented by distributions of disks [7], e.g. construction of the feature vector enables the immediate application of machine learning tools and data analysis techniques to random structures [2]
• basic sums as summary characteristics of point patterns (in preparation)
• Representative Volume Element Theory (RVE) [8]
• effective properties of 2D composite materials [6] [9] [10] [11]
• stir casting process [12]
• optimal packing problem [7] [5] [13]
• analysis of the collective behaviour of bacteria [14]

## Target audience¶

Since structural sums may seem to be computationally and conceptually complex, the main goal of this package is to provide a high level of abstraction in calculations, hiding the underlying theory and algorithms. The ready-to-use package may be helpful for scientists from the field of computational materials science

The software may also attract the attention of researchers from other fields in order to experiment with structural sums as data analysis tools. Since structural sums have proven their value as carriers of geometrical information, the package can be applied to other types of data as long as the data is represented by distributions of non-overlapping disks, as wellas points, on the plane. The area of potential applications involves, for instance, plane objects frequently studied in biological and medical images.

## Requirements¶

basicsusms runs under Python 3 and is written in pure Python. The package requires following scientific packages: numpy, matplotlib, and sympy.

A basic familiarity with Python is required.

## Installation¶

Releases are hosted on PyPI, hence the easiest way to get basicsusms is to install it with pip:

pip install basicsums


Once installed the package can be tested by running:

from basicsums.tests import test
test.run()


Function test.run() executes all doctests included in package’s docstrings as well as in test files residing in the tests submodule. The above code can be run directly in python interpreter. In order to get more detailed output specify the verbose=True keyword argument.

## Contribution and citations¶

If you want to contribute, report an issue, need support or want to cooperate, contact the author with your questions.

If basicsusms contributes to your work, please acknowledge this fact by citing [1]. For underlying algorithms and methods, please mention [3] [5]. For the computational materials science theory based on structural sums, cite [6].

basicsusms is an open source software made available under the New BSD License. For details see the LICENSE file.

References

 [1] Nawalaniec, Basicsums: A Python package for computing structural sums and the effective conductivity of random composites, 2019.
 [2] Nawalaniec, Classifying and analysis of random composites using structural sums feature vector, 475 Proc. R. Soc. A, 2019, http://doi.org/10.1098/rspa.2018.0698.
 [3] (1, 2) Nawalaniec, Efficient computation of basic sums for random polydispersed composites, Computational and Applied Mathematics 37, 2237–2259, 2017.
 [4] Mityushev, W. Nawalaniec, Basic sums and their random dynamic changes in description of microstructure of 2D composites, Computational Materials Science, Vol. 97, 64–74, 2015.
 [5] (1, 2) Nawalaniec, Algorithms for computing symbolic representations of basic e–sums and their application to composites, Journal of Symbolic Computation, Vol. 74, 328345,2016.
 [6] (1, 2) Gluzman, V. Mityushev, W. Nawalaniec, Computational Analysis of Structured Media. Academic Press (Elsevier), 2018, https://doi.org/10.1016/C2016-0-00654-X.
 [7] (1, 2) Nawalaniec, Sumy bazowe i ich zastosowanie do symulacji losowych struktur, PhD dissertation, Gliwice, 2015.
 [8] Mityushev, Representative cell in mechanics of composites and generalized Eisenstein - Rayleigh sums, Complex Variables, 51, No. 8 - 11, 1033 - 1045, 2006.
 [9] Czapla, W. Nawalaniec, V. Mityushev, Effective conductivity of random two-dimensional composites with circular non-overlapping inclusions, Computational Materials Science 63, 118-126, 2012.
 [10] Berlyand, V. Mityushev, Generalized Clausius–Mossotti formula for random composite with circular fibers. J. Stat. Phys. 102 (1/2), 115–145, 2001
 [11] Berlyand, V. Mityushev, Increase and decrease of the effective conductivity of two phase composites due to polydispersity. J. Stat. Phys. 118 (3/4), 481–509, 2005
 [12] Kurtyka, N. Rylko, Structure analysis of the modified cast metal matrix composites by use of the RVE theory. Arch Metall. Mater 58(2), 357-360, 2013. doi: 10.2478/v10172-012-0198-x.
 [13] Mityushev, N. Rylko, Optimal Distribution of the Nonoverlapping Conducting Disks, Multiscale Modeling & Simulation SIAM, Vol. 10, No. 1, pp. 180-190, 2012
 [14] Czapla, V. Mityushev, A criterion of collective behavior of bacteria, Mathematical Biosciences and Engineering 14 (1), 277-287, 2017.