Logo

kidney_nhs

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 app_config.json. 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 kidney_server and kidney_service. 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 app_config.json file. Further details of how to modify these settings can be are found by viewing the documentation for the col_gen_detect attribute.

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 called 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 output.json

    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 LD_LIBRARY_PATH and 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 config, templates and constraints 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.

v1.0.0