API documentation

POST

URL: https://sampler-flask.herokuapp.com/find-points (this page)
Inputs: A dictionary with these possible entries
- input_file: constraints file (.txt)
- output_file: output file name
  - Optional: If not supplied, _out will be added to the input file name.
    For example, from input metal.txt, output will be metal_out.txt.
- n_results: the number of solutions (points) to find
  - Optional: If not supplied, will be 10.
- output_types: the output types to return, as a comma-delimited string
  - Optional: If not supplied, will be cf = component fraction.
  - types:
Output: Results file name and contents (valid points)
- Separators
  - After a file name or the last point in that file: ***
  - After each point in a file: a linebreak \n
- The number of entries in each point is:
  - For cf: The number of dimensions given in the input (constraints) file.
  - For cwtf: The number of dimensions, or one more if a balance of fomulation component (BOFC) is supplied in constraints file. To have the extra entry, a chemical formula must be supplied for each dimension, plus one more for the BOFC.

Examples

The values of entries in points may differ because Sampler uses random numbers. The number of entries will always be as below.

Input file, output file name, number of results, and output types supplied
- Inputs: {'input_file': 'mixture_with_formulas.txt', 'output_file': 'mixture_with_formulas_out.txt', 'n_results': 4, 'output_types': 'cf, cwtf'}
- Output: For each output type, results file name and 4 points
  - mixture_with_formulas_out.txt***0.000000 0.000000
    1.000000 0.000000
    0.000000 1.000000
    0.092014 0.348421
    ***mixture_with_formulas_out_cwtf.txt***0.000000 0.000000 1.000000
    1.000000 0.000000 0.000000
    0.000000 1.000000 0.000000
    0.042943 0.289223 0.667834
Input file, output file name, and number of results supplied
- Inputs: {'input_file': 'mixture_with_formulas.txt', 'output_file': 'mixture_with_formulas_out.txt', 'n_results': 4}
- Output: Results file name and 4 points
  - mixture_with_formulas_out.txt***0.000000 0.000000
    1.000000 0.000000
    0.000000 1.000000
    0.085799 0.010204
Input file and output file name supplied
- Inputs: {'input_file': 'mixture_with_formulas.txt', 'output_file': 'mixture_with_formulas_out.txt'}
- Output: Results file name and 10 points
  - mixture_with_formulas_out.txt***0.000000 0.000000
    0.500000 0.000000
    1.000000 0.000000
    0.000000 0.500000
    0.500000 0.500000
    0.000000 1.000000
    0.078311 0.450474
    0.489759 0.447691
    0.432025 0.203087
    0.774143 0.215323
Input file and output types supplied
- Inputs: {'input_file': 'mixture_with_formulas.txt', 'output_types': 'cf, cwtf'}
- Output: For each output type, results file name and 4 points
  - mixture_with_formulas_out_cwtf.txt***0.000000 0.000000 1.000000
    0.281115 0.000000 0.718885
    1.000000 0.000000 0.000000
    0.000000 0.410211 0.589789
    0.359890 0.640110 0.000000
    0.000000 1.000000 0.000000
    0.041414 0.342994 0.615592
    0.460448 0.107272 0.432280
    0.301177 0.635857 0.062965
    0.142002 0.688742 0.169256
Input file and number of results supplied
- Inputs: {'input_file': 'mixture_with_formulas.txt', 'n_results': 4}
- Output: Results file name containing 4 points
Input file supplied
- Inputs: {'input_file': 'mixture_with_formulas.txt'}
- Output: Results file name and 10 points

Python code to POST to Sampler

Because Sampler takes files as inputs, and JavaScript cannot access the filesystem, Python is recommended instead. You can use the following code.


# From https://sampler-flask.herokuapp.com/find-points

import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
import os

def r_dict_to_fields(r_dict, input_dir = ''):
    """
    Convert a dictionary of sampler parameters into fields needed for POST request.
    For example:
    {'input_file': 'data/alloy.txt', 'output_file': 'alloy_out.txt', 'n_results': 4, 'output_types': 'cf, cwtf'} ->
    {'input_file': ('data/alloy.txt', open('data/alloy.txt', 'rb'), 'text/plain'), 'output_file': 'alloy_out.txt', 'n_results': '4', 'output_types': 'cf, cwtf'}),

    :param r_dict: The dictionary of parameters.
    :type r_dict: dictionary
    :param input_dir: Optional directory containing the input_file. If not supplied, the input file must be in the directory that you run this script from.
    :type input_dir: str
    :return: The dictionary of fields for POST request.
    :rtype: dictionary
    """
    r_fields = {}
    
    if 'input_file' in r_dict:
        input_filename = r_dict['input_file']
        input_filepath = os.path.join(input_dir, input_filename)

        r_fields.update({'input_file': (input_filepath, open(input_filepath, 'rb'), 'text/plain')})

    if 'output_file' in r_dict:
        r_fields.update({'output_file': r_dict['output_file']})

    if 'n_results' in r_dict:
        n_results_str = str(r_dict['n_results'])
        r_fields.update({'n_results': n_results_str})

    if 'output_types' in r_dict:
        r_fields.update({'output_types': r_dict['output_types']})

    return r_fields

def post_api(r_dict, input_dir = ''):
    """
    Submit a POST request to Sampler.
    :param r_dict: The dictionary of parameters.
    :type r_dict: dictionary
    :param input_dir: Optional directory containing the input_file. If not supplied, the input file must be in the directory that you run this script from.
    :type input_dir: str
    :return: The response from POST request.
    :rtype: response
    """

    url = 'https://sampler-flask.herokuapp.com/find-points'

    r_fields = r_dict_to_fields(r_dict, input_dir)

    mp_encoder = MultipartEncoder(
    fields = r_fields
    )

    # Adapted from https://discuss.dizzycoding.com/how-to-send-a-multipart-form-data-with-requests-in-python/
    r = requests.post(
        url,
        data=mp_encoder,  # The MultipartEncoder is posted as data, don't use files=...!
        # The MultipartEncoder provides the content-type header with the boundary:
        headers={'Content-Type': mp_encoder.content_type}
    )

    return r

def main():
    """Supply parameters and POST a Sampler request
    This is the code you should modify with your input parameters"""

    # Specify an input_dir
    r_dict = {'input_file': 'mixture_with_formulas.txt', 'output_file': 'mixture_with_formulas_out.txt', 'n_results': 4, 'output_types': 'cf, cwtf'}    
    input_dir = 'data/constraints'
    r = post_api(r_dict, input_dir)

    # If input (constraints) file is in directory you run this script from, 
    #   you can use this simplified two-line syntax:
    r_dict = {'input_file': 'mixture_with_formulas.txt', 'output_file': 'mixture_with_formulas_out.txt', 'n_results': 4, 'output_types': 'cf, cwtf'}    
    r = post_api(r_dict)

    # Optional--just to check the return value during debugging
    print(r.text)

if __name__ == '__main__':
    main()