It's possible that finding a solution no longer becomes practical to do with the web API.
For example, when finding a value to set the HTTP client timeout becomes problematic due to the time
taken to find a solution, or when we can no longer identify all the possible
cycles. At this point it's likely that the command line application
kidney_nhs will be required.
kidney_nhs is an application that works under Solaris, Windows and Linux - for the latter two
the CPLEX solver is also supported through
setting the appropriate values in the
The application may also use column generation to provide an optimal solution and in this case it should be noted that
the output may be different to that output by the
details of the differences in output when column generation is used are described in the
Column Generation Output section.
The use of column generation is detected by attempting to identify all the cycles but stopping when some threshold is
reached. This threshold can be raised/lowered/turned off using settings in the
Further details of how to modify these settings can be are found by viewing the
documentation for the
The application supports several arguments the details of which are listed below:
-i [ --input ] arg the file containing the kidney exchange data (required) -o [ --output ] arg the file to output the result to -t [ --type ] arg [json|xml] the output file type (default: xml) -c [ --cycle ] arg the maximum length of cycle allowed in the solution (default: 3) -f [ --format ] arg [nhsbtv1|nhsbtv2] specify the format of the output text (default: nhsbtv1) -a [ --altruistic ] arg the maximum chain length an altruistic donor can belong to (default: 1)
The arguments are similar to the parameters supplied to the REST like API with the addition of arguments for specifying an input and output file. Rather than describe each argument we provide an example of how to use the application.
Suppose we have a dataset named
input.xml, and want to find an optimal solution
that has cycles of size at most 3, chains of length at most 2, and return data in XML format in a file
output.xml then we would run the following command:
kidney_nhs -i input.xml -o output.xml -t xml -c 3 -a 1
If the extended data format
nhsbtv2 is to be used (for the reasons described in
nhsbtv2 output format section) then
we can run the following command on the same dataset as above
to find cycles of size at most 4, chains of length at most 5, and return data in json
format in a file called
kidney_nhs -i input.xml -o output.json -t json -c 4 -a 5 -f nhsbtv2
If CPLEX is to be used you must ensure that the shared library
libcplex125.so on Linux and
cplex125.dll in Windows (supplied in the downloaded archive)
can be found on the
PATH environment variables respectively -
the easiest way to do this is to just add the full path to the directory where you have extracted the application to,
to the appropriate variable. Furthermore, you must also set the environment variable
ILOG_LICENSE_FILE to contain the full path to the CPLEX license file.
Finally the application depends on files found in the
directories of the application and expects these directories to be on the current working path. Therefore if you run the application on the command
line you must first programmatically cd to the installation directory to run the application.