## tools.CreateValvesFromPointsTool


The Create Valves from Point Locations tool from MIKE+ (water distribution only).


Usage

``` python
tools.CreateValvesFromPointsTool(database)
```


Reads a point shapefile and adds one valve to `mw_Valve` per point. A point within the search radius of a junction with one or two pipes gets a valve at that junction: the valve takes the first `valve_length` of a pipe and a new junction joins the two. Otherwise, the nearest pipe within the search radius is split where the point projects onto it, and the valve takes `valve_length` centred there. Points that can't be placed are skipped with a message.

The points must be in the model's coordinate system.


## Examples

``` python
>>> import mikeplus as mp
>>> from mikeplus.tools import CreateValvesFromPointsTool
>>> db = mp.open("path/to/model.sqlite")
>>> tool = CreateValvesFromPointsTool(db)
>>> messages = tool.run(
...     "path/to/valves.shp",
...     search_radius=5.0,
...     valve_length=1.0,
...     muid_field="ID",
...     type_field="VTYPE",
... )
>>> print(messages[0])
2 valves have been created out of 3 points in the input file
>>> db.close()
```


## Methods

| Name | Description |
|----|----|
| [__init__()](#__init__) | Initialize the CreateValvesFromPointsTool with the given Database. |
| [run()](#run) | Create valves at the points in a shapefile. |

------------------------------------------------------------------------


#### \_\_init\_\_()


Initialize the CreateValvesFromPointsTool with the given Database.


Usage

``` python
__init__(database)
```


##### Parameters


`database: Database`  
A Database object for a MIKE+ water distribution model.


------------------------------------------------------------------------


#### run()


Create valves at the points in a shapefile.


Usage

``` python
run(
    points_file,
    search_radius,
    valve_length,
    *,
    muid_field=None,
    type_field=None,
    status_field=None,
    diameter_field=None,
    setting_field=None,
    description_field=None
)
```


The `*_field` arguments name the shapefile column to read each valve attribute from. Attributes without a column keep the MIKE+ defaults. Column names are matched case-insensitively. Values that can't be read fall back to a default and add a message.

If the database was closed after the tool was created, it is opened again.


##### Parameters


`points_file: str or os.PathLike`  
Path to a point shapefile (`.shp`).

`search_radius: float`  
How far from each point to look for a junction or pipe, in model units.

`valve_length: float`  
Length of each new valve, in model units.

`muid_field: str = None`  
Column with the valve ID. Missing or already used IDs get a generated one.

`type_field: str = None`  
Column with the valve type: a number from 1 to 6 or one of `PRV`, `PSV`, `PBV`, `FCV`, `TCV` and `GPV`. Other values become `PRV`.

`status_field: str = None`  
Column with the valve status: 0 (regulating), 1 (open) or 2 (closed). Other values become regulating.

`diameter_field: str = None`  
Column with the valve diameter.

`setting_field: str = None`  
Column with the valve setting.

`description_field: str = None`  
Column with the valve description.


##### Returns


`list[str]`  
Messages from MIKE+. The first summarises how many valves were created out of how many points; the rest explain each point that was skipped and each value that couldn't be imported.


##### Raises


`ValueError`  
If the model is not a water distribution model, if `search_radius` or `valve_length` is not a positive finite number, if `points_file` is not a point shapefile, or if a `*_field` names a column the shapefile doesn't have.

`FileNotFoundError`  
If `points_file` does not exist.

`DatabaseError`  
If MIKE+ fails while creating valves. Valves created before the failure are kept.