energy-tools 0.1.2

Modest collection of electrical energy calculation tools.

energy_tools

Modest collection of electrical energy calculation tools.

Note: This repo is currently being translated to English and under heavy alterations to make it suitable for PyPi. Major changes are to be expected.

Content:

• Installation
  • Requirements
  • [Installation energy-tools](#Installing energy-tools)
    • With pip
    • Without pip
    • Development version
  • Test your installation
• Features
  • complex
  • energy_factors
  • misc
  • per_unit
  • phasor
• Usage
• Contributing

Installation

Requirements

Basic requirements:

• Python 3.6+;
• numpy.

Development requirements:

• pre-commit;
• pytest;
• twine.

Installing energy-tools

With pip

1. Open a command prompt (e.g. Start > cmd on windows systems);
2. Install energy-tools by running:

pip install energy-tools

Without pip

If you don’t have internet access on your system or don’t want to use pip for some other reason, energy-tools can also be installed without using pip:

1. Download and unzip the current energy-tools distribution from PyPi under “Download files”.
2. Open a command prompt (e.g. Start > cmd on Windows) and navigate to the folder that contains the setup.py file with the command cd :

cd %path_to_energy-tools%\energy-tools-x.x.x\

Install energy-tools by running :

python setup.py install

Development version

To install the latest development version of energy-tools from GitLab, simply follow these steps:

1. Download and install git.
2. Open a git shell and navigate to the directory where you want to keep your energy-tools files.
3. Run the following git command:

git clone https://gitlab.com/miek770/energy-tools.git

4. Navigate inside the repository and check out the develop branch:

cd energy-tools
git checkout develop

5. Install Black using pre-commit:

pre-commit install

5. Set your Python path to the outer energy-tools folder (/energy-tools, NOT energy-tools/energy-tools).
6. If necessary, install missing dependencies via pip install (see Development requirements above).

Test your installation

To test your installed development version, run pytest from the energy-tools' base directory:

pytest

Features

energy_tools currently includes the following modules:

complex

The complex module includes an improved complex class which adds the following attributes (properties): phase, module.

• complex.phase returns the complex number's phase in degrees.
• complex.module returns the complex number's amplitude.

The complex module also includes a complex_impedance function that returns an improved complex number, based on a provided real impedance z and an X/R ratio.

The complex class must be imported in order for many of the other tools to be usable:

builtin_complex = complex #  If desired.
from energy_tools.complex import complex

See Usage below for more details.

energy_factors

The energy_factors module includes functions to calculate yearly energy factors for special calculations. Currently, it includes the utilisation_factor and loss_factor functions.

misc

The misc module includes basic functions to manipulate impedances, including serie, parallel, zCap and zInd. These calculate series impedance, parallel impedances, capacitance impedance and inductance impedance respectively.

per_unit

The per_unit module includes functions that return the base current, impedance and power.

phasor

The phasor module includes a new data type Phasor for the electrical phasor used in power systems.

A phasor is defined by an amplitude and a phase. The instance can be created either using those, or by providing a complex amplitude (in this case the phase is ignored). Several operations are supported, including: addition, substraction, multiplication, division, power, inversion and equality with either another phasor, a float or an integer.

It also provides a nice representation in this form: 120.000 @ 0.000°

Attributes:

• amp: The unitless phasor amplitude.
• pha: The phasor's phase in degrees.
• real: The phasor's real part (interpreted as a complex number).
• imag: The phasor's imaginary part (interpreted as a complex number).

The phasor module also includes functions sequences and phasors. The former retuns phase A's sequence voltages from phase A, B and C's voltages. The latter does the opposite, i.e. it returns phase A, B and C's voltages from phases A's sequence voltages.

Usage

Sample usage may be found in the tests directory. Most of these tools are straightforward (or aim to be), so the tests and docstrings should be helpful enough.

As mentioned above, the complex class must be imported in order for many of the other tools to be usable:

builtin_complex = complex #  If desired.
from energy_tools.complex import complex

When the improved complex type is imported this way, the following call will result in variable a being an energy_tools.complex.complex instance, as expected:

a = complex(1, 1)
a.phase #  Will return 45 degrees

Implicitly declaring a complex number, however, will return the built-in complex type:

a = 1 + 1j
a.phase #  Will raise AttributeError

Contributing

If you wish to contribute, please follow the development version instructions above and refer to the project's contribution guide.