Metadata-Version: 2.4
Name: sDNA_plus
Version: 5.2.0
Summary: sDNA is a world leading tool for Spatial Design Network Analysis.  
Project-URL: Homepage, https://sdna.cardiff.ac.uk/sdna/
Project-URL: Source code, https://github.com/fiftysevendegreesofrad/sdna_plus/tree/Cross_platform
Project-URL: Bug Tracker, https://github.com/fiftysevendegreesofrad/sdna_plus/issues
Author-email: Crispin Cooper <sdna@cardiff.ac.uk>, James Parrott <james.parrott@proton.me>
License: ## License for all sDNA code unless otherwise stated: AGPL v3.0
        
        sDNA software for spatial network analysis 
        Copyright (C) 2011 onwards Cardiff University
        
        This program is free software: you can redistribute it and/or modify
        it under the terms of the GNU Affero General Public License as
        published by the Free Software Foundation, either version 3 of the
        License, or (at your option) any later version.
        
        This program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU Affero General Public License for more details.
        
        https://www.gnu.org/licenses/agpl-3.0.en.html
            
        ## License for sDNAUISpec.py
        
        This file is released under the MIT license to ease any licensing issues that may arise if incorporating in plugins to proprietary software. See sDNA.pyt or the sDNA QGIS plugin for examples of its use.
        sDNAUISpec specifies a user interface and the means to produce calls to the sDNA command line tools from user input. The command line tools use standard data formats (shapefile or gdb) for interchange and can be used independently of sDNAUISpec, we consider this weak linkage to be permissible under GPL principles (otherwise it would not be possible to run open source tools on a proprietary operating system, or vice versa).
        
        ### MIT License
        
        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.
        
        ## Licenses for libraries used in sDNA
        
        shapefile.py - MIT license as above.
        
        muparser has its own permissive license, see muparser source files for details.
        
        GEOS shared library is licensed under GNU LGPL, see GEOS source files for details.
        
        R-portable is licensed under GPL version 3, as a command line tool this is weakly coupled. (It would be possible for the user to use their own installation of R in combination with the sDNA Learn/Predict tools; we provide it in the installer for convenience).
License-File: LICENSE.md
Keywords: GIS,Spatial Networks,Urban planning
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Requires-Python: >=3
Requires-Dist: numpy
Requires-Dist: pyshp==2.4.2
Provides-Extra: learn
Provides-Extra: predict
Provides-Extra: r
Requires-Dist: rportable[i386]==3.2.3; (platform_system == 'Windows') and extra == 'r'
Description-Content-Type: text/markdown

# sDNA+: Spatial Design Network Analysis plus

This is the experimental [Cross Platform](https://github.com/fiftysevendegreesofrad/sdna_plus/tree/Cross_platform) branch of sDNA+, now available for Linux as well as Windows.

## Quick start

### Python

If working on the command line (outside of ArcGIS, QGIS and Rhino3D for which there are plug-ins) sDNA is most 
conveniently run via Python.  uv makes this easy, and results in the fewest problems (e.g. issues with the 
operating system that may occur with other Python installers).

#### uv
In general one should never run untrusted code straight from the internet (please don't!).
However (to the horror of the security conscious) installing 
[uv](https://github.com/astral-sh/uv) is easiest by running either their Linux 
installation script:
```bash
 curl
 -LsSf https://astral.sh/uv/install.sh | sh
``` 

or their Windows one:
```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

which both download further scripts from Astral's website ([see](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_1)) and runs them directly.
Otherwise uv is also available in [various package managers](https://docs.astral.sh/uv/getting-started/installation/#winget), or by 
[downloading their executables](https://github.com/astral-sh/uv/releases), unpacking them, and appending the dir they are in to your system's Path environment variable.

#### Windows

On Windows we recommend either uv (as above), or or [pyenv-win](https://github.com/pyenv-win/pyenv-win/), 
Either option can install whichever Python versions you desire, relatively trouble free.

#### Linux

On Linux we recommend either also installing uv (as above) to provision Pythons (independent of any 
operating system Python) or simply create a Python virtual environment, e.g.

```
sudo apt-get update
sudo apt-get install -y python3-venv
```

### Isolation

If using uv, installation of the core software is straightforward:

```
uv tool install sdna_plus
```
For sDNA Learn and Predict on Windows use `uv tool install sdna_plus[R]`, or  On Linux, a separate installation of R is also required for sDNA Learn and Predict - see below.

#### Pipx

If not using uv, install your chosen Python version (if using PyEnv, you might need to 'activate' it).
Then install [`pipx`](https://github.com/pypa/pipx) into this Python.  
Pipx automatically installs Python applications into virtual environments (avoiding Python 
dependency conflicts).
```
python3 -m pip install pipx
```

Pipx can then be used to install an sDNA Wheel from PyPi (including PyShp and any other Python deps), 
and set up the run time commands:
```
pipx install sdna_plus
```
or on Windows, for sDNA Learn and Predict, `pipx install sdna_plus[R]`.  Pipx will automatically create a special virtual environment for sDNA, and add its executables to the Path environment variable.

Example command line use:
```
sdnaintegral -i input_network.shp -o output_network.shp`
```

### To use sDNA Learn or sDNA Predict
An an installation of [`R`](https://www.r-project.org/) with optparse and Car is required.  
On Windows, a portable version of R is checked into the main branch, 
or installable separately from [Rportable](https://pypi.org/project/rportable/)

#### Installing R on Linux 

Install R and the two R deps separately, e.g. on Ubuntu with:
```
sudo apt-get update
sudo apt-get install -y r-cran-optparse r-cran-sjstats # Warning!  Can need 3.5GB
pipx install sdna_plus
```

or set up [r2u](https://eddelbuettel.github.io/r2u/).


#### Using R Portable 3.2.3 (Windows only). 
This is the same [R-Portable](https://github.com/JamesParrott/rportable) as bundled 
with sDNA previously.  Requires ~100MB.  E.g.:
```
pipx install sdna_plus[R]
```


## Notes
On Linux there are five unsolved regressions (compared to the Windows build), which may or may not be important.
See issues #61, #65, #83, #84, and #83.

The Linux Wheel, including `geos_c.so` as well as `sdna_vs2008.so` is built in a Docker image based on the 
oldest (now unsupported) ManyLinux image.  See `Dockerfile.build`.  It is compiled with GCC 4.8 ish, so 
different run time behaviour is possible between it and both the GCC and zig c++ Linux builds.  A 
build hook (`./hatch_build.py`) triggers a near normal CMake build of sDNA, and Hatchling 
repackages the standard sDNA output directory for PyPi (instead of just zipping it 
or running AdvancedInstaller on Windows).

## History

This is the open source fork of the formerly proprietary sDNA+ software - all the sDNA features plus hybrid metrics. 

sDNA+ was created by Crispin Cooper on behalf of [Cardiff University](https://www.cardiff.ac.uk).  Alain Chiaradia was responsible for the initial idea, and Chris Webster for the initial funding and project mentoring. We are grateful to various parties for financial contributions towards development: in no particular order, Hong Kong University, Tongji University, the UK Economic and Social Research Council, BRE, Wedderburn Transport Planning. Also research contributions in kind from Arup Ltd, WSP Global Engineering, BuroHappold and Sustrans. Also to James Parrott both for developing the [sDNA for Grasshopper](https://github.com/fiftysevendegreesofrad/sDNA_GH) plugin, and for assistance in updating the sDNA build process during 2023. And Jeffrey Morgan for updating sDNA to Python 3.  Robin Lovelace (University of Leeds) figured out how to enable OpenMP support on Linux (for multi-threading).

If you are interested in sponsoring changes to sDNA, please get in touch with Crispin cooperch@cardiff.ac.uk.

Copyright rests with Cardiff University and the code is released under GPL Affero version 3.

## For Users

### Installation

Use the software via any of the following means:

* QGIS 2.14 onwards
  * as well as installing sDNA, you will need to install the sDNA QGIS plugin from the QGIS plugins dialog.
* ArcGIS 10.2 onwards, and ArcGIS Pro
  * as well as installing sDNA, you will need to add the toolbox found in the sDNA install folder to the Arc toolbox. 
* Autocad
  * We discountinued the old Autocad interface as it doesn't process attached data. If using Autocad, we recommend export/import of shapefiles using Autocad Map3d, then use sDNA from the free QGIS
* Add the `bin` folder to your path and use sDNA command line scripts
  * To see examples of command line calls, run sDNA from QGIS, the plugin will tell you what command line it uses for each task
* Use the Python interface `sdnapy.py`; look at `runcalculation.py` for the reference example of how to do this

### Documentation

Hosted on [readthedocs](https://sdna-plus.readthedocs.io/en/latest/).

### Support

Please see the original project [support page](https://sdna.cardiff.ac.uk/sdna/support/).

If filing a bug, please file to [the database here on github](https://github.com/fiftysevendegreesofrad/sdna_plus/issues). 

## For Developers
See BUILD.md for notes regarding the impact of switching to CMake from sdna_vs2008.vcxproj

### Experimental Linux build
Requires the `Cross_platform` branch.  The GCC builds are prioritised, but the 'Clang' builds (using `zig c++`) have been invaluable.
There are  a handful of open regressions (compared to the Windows build), which may or may not be important.
#### Installation
* Build from source (see `./BUILD.md`) or if on Ubuntu, download and unzip an "output" installation directory from a Github Action that built it ([e.g.](https://github.com/fiftysevendegreesofrad/sdna_plus/actions/runs/9584489142)).  If the artifacts have expired, a public fork can
be made, on which Github Actions can be run for free.  Using this, the "CMake, GCC & Ubuntu" one will rebuild it for
you automatically in about 5 minutes.  The copy of `libgeos_c.so` may require a specific version of glibc.  If this is not available, it will have to be recompiled (see `./BUILD.md` or `.github/workflows/build_geos.yml`).
* Create a venv and activate it (to avoid installing packages into the operating system's Python, and to isolate Numpy).
* Install PyShp and any other deps: `pip install -r requirements/base.txt`
* The entry points in './bin' should be able to be used as normal.
* The Python API may first require: `SDNADLL=/path/to/output/Release/x64/sdna_vs2008.so`  
* If sDNA Learn or Predict is required:
  - To install Numpy (and anything else) `pip install -r requirements/learn-predict.txt`
  - R (and the "optparser" and "can" packages) must be installed separately, e.g. on Ubuntu: 
```
sudo apt-get update
sudo apt-get install -y r-cran-optparse r-cran-sjstats
```
### Building the software

#### Local build requirements:

* Microsoft Visual Studio (tested on 2022) with C++ extensions
* Python
* Advanced Installer.  Add the location of `AdvancedInstaller.com` either to your path (`%PATH%`) or to line 8 of `build_installer.proj`.
* Vcpkg (tested with vcpkg.exe `version 2024-04-23-d6945642ee5c3076addd1a42c331bbf4cfc97457`).  E.g. in the chosen parent dir:
   - `git clone --depth=1 https://github.com/microsoft/vcpkg/`
   - `cd vcpkg`
   - `setx VCPKG_ROOT c:\path_to_vcpkg_repo\vcpkg`
   - `.\bootstrap-vcpkg.bat`
* 5-6 GB free disk space (to be safe).

Fire up the Visual Studio Developer Command Prompt. 
 - Before the first use of vcpkg, in the vcpkg repo root call [`.\vcpkg.exe integrate install`](https://learn.microsoft.com/en-gb/vcpkg/users/buildsystems/msbuild-integration)
 - Then in the sDNA repo's root call `build_release.bat` which should do what it says on the tin.

#### CI build and test requirements:
* Run the Github Action `.github\workflows\compile_and_test.yml`

#### CMake build requirements:
* CMake (tested on 3.27.7.  At least 3.16 is required for precompiled headers),
* as for "Local build requirements" above (without Advanced Installer and without integrating vcpkg).
* To build in cmd (or a shell with a character limit too low for CMake and the deeply nested R-portable tree) it may be
necessary to open an admin Powershell terminal and run: 
```
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" 
-Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
```
CMake ideally wants build trees to be separate from source trees.  But in order 
for `sDNA\sdna_vs2008\version_generated.h.creator.py` to be able to extract a commit hash, 
the build tree must at the very least live within a copy of the sDNA Git repo.  So for now 
we'll pretend the source tree is `.\sDNA\` and put the 'build tree' in `.\build_cmake`.

CMake's Visual Studio Generator is a multi-config generator.  This would be handy for
creating a Release build in parallel with a Debug build.  Unfortunately it is not a 
multi-platform generator (sDNA's installer contains Release Win32 and Release x64 DLLs).
CMakeLists.txt needs to be invoked and built from twice therefore, to produce a Windows installer.

Running (in a normal cmd.exe, not the VS Developer Command Prompt):
 - `.\create_installer_with_CMake.bat`
should create `sDNA_setup_win_vX.msi`.

### Dependencies

#### Boost
It is not immediately visible, but Boost 1.83 is used currently. Vcpkg manifest mode uses hashes of git commits of its own repo to define baselines from which dependencies are drawn.  These are in `sDNA\sdna_vs2008\vcpkg-configuration.json`.  For example `61f610845fb206298a69f708104a51d651872877` refers to https://github.com/microsoft/vcpkg/commit/61f610845fb206298a69f708104a51d651872877 of Nov 11th 2023, on which date the latest version of Boost in vcpkg was 1.83
https://learn.microsoft.com/en-gb/vcpkg/consume/boost-versions

It is possible to use an override mechanism to pin deps instead, but this would make `sDNA\sdna_vs2008\vcpkg.json` much longer.  https://learn.microsoft.com/en-gb/vcpkg/consume/lock-package-versions?tabs=inspect-powershell#5---force-a-specific-version

#### Geos
Geos v3.3.5 is dynamically linked at run-time.  A custom build step copies in the `geos_c.dll`s (from `sDNA\geos\x64\src`
and `sDNA\geos\x86\src`), originally compiled for OSGEO4W available hereabouts: https://download.osgeo.org/osgeo4w/v2/x86_64/release/geos/ .  On Linux `geos_c.so` is first compiled in the build environment, see e.g. `.github\workflows\build_geos.yml` 
or in the oldest manylinux image for greatest compatibility: `Dockerfile.build`.

#### Muparser
A static copy of [`Rev 2.2.3: 22.12.2012`](https://launchpad.net/ubuntu/+source/muparser/2.2.3-6).  Changes:
 * `#define MUP_BASETYPE float` in sDNA\muparser\drop\include\muParserDef.h
At build time on Windows, using MSVC and MSBuild (no CMake), the source code is dynamically changed.
A custom prebuild step (`sDNA\sdna_vs2008\preppend_muparser_cpps_with_include_stdafx.h.py`) makes each Muparser file
compatible with Visual Studio's particular (not force included) pre-compiled header rules.

#### Anyiterator
```
// Revision History
// ================
//
// 12 Jul 2010 
```
#### R-portable
Version 3.2.3.  Available here: https://sourceforge.net/projects/rportable/files/

### Packaging
The Windows installer contains x64 and Win32 binaries (for both `sdna_vs2008.dll` and `geos_c.dll`)

### Project Structure

Some key folders:

* `sDNA` - C++ projects
  * `sdna_vs2008` - the core sDNA dll
  	* `tests` - tests of the above
  * `geos`, `muparser` - dependencies of `sdna_vs2008`
* `arcscripts` - originally just for ArcGIS, now also comprises the QGIS, Python and command line interface
  * `bin` - command line tools
  * `sdnapy.py` - python interface
  * `sDNAUISpec.py` - defines user interface for both ArcGIS and QGIS
    * ArcGIS interprets this via `sDNA.pyt`
    * QGIS code to interpret this is found in the [QGIS sDNA Plugin](https://plugins.qgis.org/plugins/sdna/)
* `installerbits` - extras needed to create install package
* `docs` - documentation

### Tests


#### Continuous Integration Tests.
##### Test pollution
The tests are based on regressions tests against test files, from test procedures defined in .bat files.  
Some rely on artefacts from previous tests (they are intended to be run sequentially) so the individual
PyTest test cases based on these should not be run without those previous to it, the files written
by which it relies on.

##### Description
Currently, the CI tests are a subset of sDNA's regression tests, which diff the test output against that produced by a previous build (eight of the expected output files can be recreated using `sDNA\sdna_vs2008\tests\approve_debug_output.bat`, but `correctout_learn.txt` and `correctout_table.txt` require other means).

The CI test runner parses every `.bat` file in `sDNA\sdna_vs2008\tests` except the following which are filtered out:
`colourdiff.bat`, `mydiff.bat`, `awkward_test.bat`, `arc_script_test.bat`,`run_tests_windows.bat`, `sdnavars64.bat`,`quick_test.bat` ( as it reruns `debug_test.py` which is already tested in `pause_debug_test.bat`) and `run_benchmark.bat` (to avoid issue 11, an unexplained "Access violation on Python 3").

To run the CI tests locally, something like the following commands are required:

```
cd your_venvs_directory
python -m venv sdna_testing_venv
.\sdna_testing_venv\Scripts\activate
pip install pytest
cd path_to_sdna_plus_repo\sdna_plus\sDNA\sdna_vs2008\tests\pytest
```
then either on Windows in cmd.exe:
```cmd
set DONT_TEST_N_LINK_SUBSYSTEMS_ORDER=1 & set ALLOW_NEGATIVE_FORMULA_ERROR_ON_ANY_LINK_PRESENT=1 & pytest -rA
```
or in Bash:
```bash
DONT_TEST_N_LINK_SUBSYSTEMS_ORDER=1 && ALLOW_NEGATIVE_FORMULA_ERROR_ON_ANY_LINK_PRESENT=1 && pytest -rA
```

The CI test runner (`sDNA\sdna_vs2008\tests\pytest\test_gathering_windows_command_line_tests.py`) is designed to be invoked via Pytest.  It can also run either all the tests or the test at a specific index if run as a script.  It is influenced by the following environment variables:
 - `sdna_debug` - By default it is assumed release builds are tested, so this is Falsey - i.e. an empty string (do not use 0 or "False" as in Python `bool("0") is True` and `bool("False") is True`).  If so, then the output lines resulting from the parts of sDNA's C++ source code, that are only compiled if the pre_processor directive `_SDNADEBUG` is set, are omitted from the "expected" output.  Set this to something Truthy (any non-empty string other than `False`) if testing a debug build.
 - `sdnadll` - the path to the `sdna_vs2008.dll` to test.  By default the test runner tries to run a fair test, by using the Python files associated with an sDNA installation, or those in a repo containing a `sdna_vs2008.dll` resulting from running the compilation process.  It is also possible to set `sdna_bin_dir` to any directory containing the required sDNA `.py` files.
 - `DONT_TEST_N_LINK_SUBSYSTEMS_ORDER` - must be set to something Truthy, to work around issue 20.
 - `ALLOW_NEGATIVE_FORMULA_ERROR_ON_ANY_LINK_PRESENT` - must be set to something Truthy, to work around issue 21.

Various other quality of life adjustments are made, such as ignoring blank lines, and Progress bar percentage lines.

#### Old testing routine.

Currently the steps outlined below may not work, but what *does* work is setting appriate paths for `python2exe`, `python3exe`, and `sdnadll` (which should be 32 or 64 bit depending on the Python executable) then calling `pause_debug_test.bat`.

For testing the core network processing and numerical routines, fire up the `sdna_vs2008.sln` solution in `sDNA\sDNA_vs2008`. 
You will need the correct debug settings; unfortunately Visual Studio stores these with user information. Copy `sdna\sdna_vs2008\sdna_vs2008.vcproj.octopi.Crispin.user.sample` on top of your own `sdna_vs2008.vcproj.yourmachine.yourusername.user` file.
Set build configuration to `Debug Win32`, and run. This calls scripts in `sDNA\sDNA_vs2008\tests` and diffs the output with correct outputs (the core of which are originally hand computed) in that directory. Any call to `diff` that shows differences is a test fail.

For `test_parallel_results.py` to work, you also need to build the `parallel_debug Win32` configuration. When `Debug Win32` is run as described above, serial and parallel results are compared to check they are identical.

Interfaces are not automatically tested, though `arcscripts\sdna_environment.py` can be tested by `environment_test.py`.

### Future

The long term roadmap includes moving to reproducible builds (which will be nice when developers have to onboard or change machines).

## License

The bulk of sDNA+ is licensed under GNU Affero v3, with various other Free licenses for various modules. For full details see [licensing](LICENSE.md).
   
