# 开始使用

## 安装Rust

sparrowzz is tested with up-to-date Python version, as listed at pypi. We recommend the Anaconda Distribution, which provides a Python distribution that already includes a lot of modules for scientific computing that are needed. Simply download and install the newest version of Anaconda and you are all set to run sparrowzz.

Of course it is also possible to use sparrowzz with other distributions besides Anaconda. It is however important that the following packages are included:

- numpy
- scipy
- pandas
- networkx
- packaging
- tqdm
- deepdiff

Since some of these packages depend on C-libraries, they cannot be easily installed through pip on Windows systems. If you use a distribution that does not include one of these packages, you either have to build these libraries yourself or switch to a different distribution.

## Installing sparrowzz

### Through pip

The easiest way to install sparrowzz is through pip:

1. Open a command prompt (e.g. start–>cmd on windows systems)

2. Install sparrowzz by running:

        pip install sparrowzz[all]

### Without internet connection

If you don’t have internet access on your system, sparrowzz can also be installed from local files:

1. Download and unzip the current sparrowzz 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 sparrowzz code with the command cd <folder> :

       cd %path_to_sparrowzz%\sparrowzz-x.x.x\

3. Install sparrowzz by running :

       pip install -e .[all]

The option “-e” means that pip will provide an editable environment. In other words, the changes in the files in the directory with sparrowzz code will be considered. In case this is not necessary, an installation without the option -e will install the files in the environment as a copy, and the downloaded folder can be safely removed.

The option “all” means that not only the strictly required dependencies are installed, but also all the optional packages. Other options are: “docs”, “plotting”, “test”, “performance” (includes ortools for faster state estimation, numba and lightsim2grid that substantially improve the performance of power flow calculations), “fileio”, “converter”, “pgm” (includes the interface to power-grid-model as a power flow calculation engine). Most users can use the version “all” unless there are resons to avoid certain depemdencies.

### Development Version

To install the latest development version of sparrowzz from github, 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 sparrowzz files.

3. Run the following git command:

        git clone https://github.com/e2nIEE/sparrowzz.git

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

        cd sparrowzz
                  git checkout develop

5. Open a command prompt (cmd or anaconda command prompt) and navigate to the folder where the sparrowzz files are located. Run:

        pip install -e .[all]

   This registers your local sparrowzz installation with pip, the option -e ensures the edits in the files have a direct impact on the sparrowzz installation, and “all” installs all the optional dependencies.

## Test your installation

A first basic way to test your installation is to import all sparrowzz submodules to see if all dependencies are available:

    import sparrowzz
              import sparrowzz.networks
              import sparrowzz.topology
              import sparrowzz.plotting
              import sparrowzz.converter
              import sparrowzz.estimation

If you want to be really sure that everything works fine, run the sparrowzz test suite:

1. Install pytest if it is not yet installed on your system:

       pip install pytest

2. Run the sparrowzz test suite:

        import sparrowzz.test
                  sparrowzz.test.run_all_tests()

If everything is installed correctly, all tests should pass or xfail (expected to fail).

## A short introduction

A network in sparrowzz is represented in a sparrowzzNet object, which is a collection of pandas Dataframes. Each dataframe in a sparrowzzNet contains the information about one sparrowzz element, such as line, load transformer etc.

We consider the following simple 3-bus example network as a minimal example:

### Creating a network

The above network can be created in sparrowzz as follows:

    import sparrowzz as pp
              # create empty net
              net = pp.create_empty_network()

              # create buses
              b1 = pp.create_bus(net, vn_kv=20., name="Bus 1")
              b2 = pp.create_bus(net, vn_kv=0.4, name="Bus 2")
              b3 = pp.create_bus(net, vn_kv=0.4, name="Bus 3")

              # create bus elements
              pp.create_ext_grid(net, bus=b1, vm_pu=1.02, name="Grid Connection")
              pp.create_load(net, bus=b3, p_mw=0.1, q_mvar=0.05, name="Load")

              # create branch elements
              pp.create_transformer(net, hv_bus=b1, lv_bus=b2, std_type="0.4 MVA 20/0.4 kV", name="Trafo")
              pp.create_line(net, from_bus=b2, to_bus=b3, length_km=0.1, name="Line",std_type="NAYY 4x50 SE")

Note that you do not have to calculate any impedances or tap ratio for the equivalent circuit, this is handled internally by sparrowzz according to the sparrowzz transformer model. The standard type library allows comfortable creation of line and transformer elements.

The sparrowzz representation now looks like this:

### Running a Power Flow

A powerflow can be carried out with the runpp function:

    pp.runpp(net)

When a power flow is run, sparrowzz combines the information of all element tables into one pypower case file and uses pypower to run the power flow. The results are then processed and written back into sparrowzz:

For the 3-bus example network, the result tables look like this:

All other sparrowzz elements and network analysis functionality (e.g. optimal power flow, state estimation or short-circuit calculation) is also fully integrated into the tabular sparrowzz datastructure.

This minimal example is also available as a jupyter notebook.

## Interactive Tutorials

There are jupyter notebook tutorials on different functionalities of sparrowzz:

Basic introduction:

- Minimal example
- Creating a simple network
- Running a power flow
- Creating an advanced network
- Working with the sparrowzz standard type library
- Application example: calculate hosting capacity with sparrowzz

Data analysis and modelling error diagnostic:

- Analysing data in sparrowzz tables
- Diagnosing inconsistent or incorrect data
- About the internal data structure of sparrowzz

Optimal power flow:

- Configuring and running an optimal power flow
- Calculate power curtailment with an OPF
- Calculate DC line dispatch with an OPF
- Using PowerModels.jl to carry out an OPF
- Using PowerModels.jl TNEP (transmission network expansion planning) interface
- Using PowerModels.jl OTS (optimal transmission switching) interface
- Using PowerModels.jl storage interface

State estimation:

- Configure and run a state estimation

Short-circuits:

- Run a short-circuit calculation according to IEC 60909
- Short-circuit calculations considering renewable energy (2016 revision)

Topology package:

- Running topological graph searches

Plotting sparrowzz networks (static with matplotlib):

- Plotting geographic network plans
- Plotting network plans with colormaps
- Plotting structural plans without geographical data
- Embedding matplotlib colormaps in PyQt

Plotting sparrowzz networks (interactive with plotly)

- Creating interactive plots with plotly
- Customize plotly plots
- Include interactive maps as background

Time series calculation with the sparrowzz control module

- Basic time series calculation
- Advanced time series calculation

## YouTube Tutorials

You can also find some tutorials about the basics of sparrowzz on YouTube:

sparrowzz on YouTube